Configuration

Certain specific tasks can only be accomplished by editing the configuration files that display from the Configuration screen.

Configuring Stop Words

Stop words files contain a list of words that the search interface ignores unless used as part of a quoted phrase. These include words such as if, the, it, to, and so forth.

One example of a default stop word you might want to edit is the word will. It is included as a stop word because it is most commonly used as an auxiliary verb. For example, "I will go tomorrow." However if a user searches for this word as a noun, such as, "He put his nephew in his will," it is still ignored. While keeping will and similar words in the stop words file increases efficiency, removing these words increases search accuracy. Review the list of words in the file, and add or remove words as necessary.

Depending on your configuration, stop words files might be available for multiple languages.

To edit stop word files, follow the steps below:

1. In the Navigation menu, click Configuration, then select <language_code>-stopwords.txt from the menu.

2. Review the words in all available files and add or remove words as necessary by typing or deleting in the list of words provided.

3. Click save.

4. The ps-search-ui service must be restarted in order for changes to take effect. Contact professional services in order to restart it.

Configuring Search Stores

A search store contains a set of searchable data and are available to help organize data. The Search Appliance lets you create multiple search stores so that if you need to delete a large set of data, you can delete a single search store rather than deleting individual records or all data. When you create a new indexing job, if there is a set of data that you want available for only a limited period of time, you should place it in a separate search store. Four files exist that house search stores and store groups:

• SearchServer-audit.conf: audit logs

• SearchServer-aux.conf: auxiliary data--such as attestations, subscriptions, limbo records, medcodes

• SearchServer-clinical.conf: clinical record data

• SearchServer-mpi.conf: MPI data

Creating New Search Stores

1. In the Navigation menu, click Configuration, then select the desired SearchServer conf file from the menu.

2. Locate the lines that list the spaces. They'll look similar to this:

   TextText

   space-1 = records
   space-2 = labs
   space-3 = adts

3. At the end of the list, type the new store number and store name, e.g. space-32 = searchstorename. The store number must begin with space-.Do not duplicate the store number or name across the different files. Only lowercase alphanumeric characters, periods, or hyphens are recognized. When using the store in a query or report, refer to it with the name of the store, not the store number.

4. Locate the line similar to job-cgi = commitindex=2&periodsec=90 (the commit index number may be different), and add an incremented line for the new search store using the new space number assigned; for example, job-cgi = commitindex=32&periodsec=90. This tells the server to automatically commit all new records every 90 seconds.

5. Click save.

6. The ps-searchserver service must be restarted in order for changes to take effect. Contact professional services in order to restart it.

Creating Groups of Stores

There are times when the same stores are used together over and over when writing queries. If this is the case, it may be more useful to create a group containing multiple stores. After store groups are created, instead of typing multiple stores each time, the user can enter only the store group name. To create the group, follow the steps below:

1. In the Navigation menu, click Configuration, then choose the desired SearchServer conf file from the menu.

2. Locate store-groups {...}. In most cases this exists with IMAT codes and AuditLogs as default groups. If store-groups does not exist, add it.

3. Set the store group name equal to the predefined space names (not the space numbers) within the {}. Do not duplicate store group names across the different search server files.

   TextText

   store-groups { 
      ...
     AuditLogs = auditLog2016, auditLog2017, auditLog2018, auditLog2019, auditLog2020, auditLog2021, auditLog2022, auditLog2023, auditLog2024, auditLog2025
   }

4. Click save.

5. The ps-searchserver service must be restarted in order for changes to take effect. Contact professional services in order to restart it.

Excluding Stores from Searches

Currently, anywhere in the IMAT applications where selecting All stores is an option for queries, you are really selecting all stores except those specified in the SearchServer conf file. Generally stores are excluded if they do not include medical information, such as the audit log stores, or are specific to an IMAT application, such as MPI.

1. Locate the desired SearchServer conf file.

2. Locate exclude-stores.

3. Create a comma-separated list of all stores you want excluded from searches. You must use the store number and do not exclude stores across the different conf files.

   TextText

   # Specify default search stores to be included and excluded (used when no search store is specified in the query)
   
   # if include-stores is absent, the default is all minus the exclude-stores list
   # exclude-stores = 2,3
   
   exclude-stores = 1000,1002,1100,1101,1102,1103,1110,1120,1130
   

4. Click save.

5. The ps-searchserver service must be restarted in order for changes to take effect. Contact professional services in order to restart it.

Configuring Help Links

Help can be accessed through the user menu or by clicking help found below the user name. By default, clicking on the links opens documentation delivered with the IMAT appliance. However, if the need changes, you can link that help to another location. Every time "customerHelpLink": "/ui/documentation/", is found, a custom link can be inserted. Make sure you've located the correct page for customization as there is a line for each page as well as the User Menu. Follow the steps below to change the link. Remember that proper json syntax must be used.

1. Locate and open imat.json.

2. Locate the line "customerHelpLink": "/ui/documentation/",.

3. Replace the link with the desired location. Remember to include the quotation marks and comma at the end of the line.

   • Relative links point to other locations on the IMAT appliance and do not need the full URL: /ui/documentation/#/reports/overview.

   • Absolute links point to any location outside of the appliance and require the full URL: http://www.thisisthebestwebsiteever.gov/a/myfavoritepage.

4. Repeat for each link that needs updating.

5. Click save.

6. You may need to restart the imat-api service for changes to take effect.

Session Handler Timeout

If a user is inactive for too long after logging in, the system times out and the user is required to log in to his or her account again. Adjusting the timeout in the session handler can increase the amount of time a user has before he or she is logged out.

1. Locate api.json.

2. Change the value for "sessionTimeoutInMinutes".

3. Click save.

Login Page

You may change the default URL for the login page if your organization uses SSO or two-factor authorization for logging in. When a user is logged out, IMAT will send users to the when, for example, their session expires.

1. Locate api.json.

2. Change the value for "loginPage".  

3. Click save.

Configuring MPI Gender Field Options

It is possible to change the gender labels as they are displayed on the MPI Lookup form or the MPI Limbo lookup form. Keep in mind as you are formatting these fields that the "value" is directly related to the specified field as it is alphanormalized when the data is consumed into the search server and must match that information; therefore, it should not be changed. However, if you find that you have more gender options in your data than found in the drop-down list, you can add the corresponding "label" to the form. Correct json syntax must be used.

1. Locate the persona-search.json or limbo-search.json file.

2. Find "options" found in the "gender" code block.

3. Enter the labels as you'd like them to appear on the MPI lookup form.

   JSONJSON

   "gender": {
     "display_name": "Gender",
     "name": "s.patient_sex",
     "type": "select",
     "options": [
       {
         "value": "male",
         "label": "Male"
       },
       {
         "value": "female",
         "label": "Female"
       }
     ],
     "placeholder": "e.g. male"
   },
   

4. Click save.

5. Contact professional services to apply your changes to the server.

Note, unless you have received training, don't change anything else in the file.

PHI Access

Some of IMAT's tools require permission to view PHI. By default, the software allows only administrators to view the information on those tools; however, the permissions are configurable to meet needs. The below code, named phi_access.json, is the default delivered with the IMAT software:

{
  "accessTimeout": "24", // This is the number of hours access is allowed before access expires.
  "sessionOnly": true, // This is a Boolean which controls whether or not to clear attestations on new logins; a missing property is treated as false.
  "workflow": { // Each configuration block is nested under a root property of the object called "workflow". The child properties of "workflow" are the step names. Each step name may be any valid string except for reserved names. Currently the only reserved name is "Start".
    "Start": { // This is required.
      "actions": { // This is required.
        "confirm": true, // True successfully exits the workflow and allows the user to see PHI. The other option is to send the user to the next step of the process. See #/advanced/admin/configuration#phi-options for more examples.
        "reject": false // False unsuccessfully exits the workflow and blocks the user from viewing PHI.
      },
      "groups": ["searchappliance_system"], // This is an array of groups that are allowed to see PHI.
      "type": "GroupCheck" // This checks the groups property (an array of groups) against the user's groups. If a user belongs to any of the groups in the array, action.confirm is automatically executed. If no groups match, action.reject is automatically executed.
    }
  }
}

Those with the proper access and knowledge can also access the file at /opt/search/default/conf/phi_access.json.

As mentioned above, the file can require users to read attestation agreements, choose to accept or decline the disclaimer, give the user options from a list, etc. Below is an example of a file with various blocks of attestation. Follow the code below to see how one block flows into another until all of the desired checks are complete.

{
  "accessTimeout": "24",
  "initialAttestationMetadata": { // Sets up which properties will be accepted and what their default values are.*
    "attested_patient": null,
    "broke_glass": null,
    "modified_consent": null,
    "view_bh": null
  },
  "workflow": {
    "Start": {
      "actions": {
        "confirm": "PatientConsentYes",
        "reject": "AccessReason"
      },
      "groups": ["requires_consent_group"],
      "type": "GroupCheck"
    },
    "AccessReason": {
      "actions": {
        "confirm": true,
        "reject": false
      },
      "content": {
        "title": "Access Reason",
        "body": {
          "type": "text",
          "value": "Why are you accessing this data?"
        },
        "input": {
          "type": "text",
          "options": []
        },
        "btn_confirm": {
          "label": "Submit"
        },
        "btn_reject": {
          "label": "",
          "visible": false
        }
      },
      "type": "Prompt"
    },
    "PatientConsentYes": {
      "actions": {
        "confirm": "Redisclosure1",
        "reject": "BreakTheGlassGroupCheck"
      },
      "compare": {
        "operator": "==",
        "query": "()mpid:{mpid}",
        "value": "Y",
        "field": "consent",
        "store": "Consent"
      },
      "type": "QueryCheck" // This allows a custom query to run.**
    },
    "Redisclosure1": {
      "actions": {
        "confirm": "Redisclosure2",
        "reject": false
      },
      "content": {
        "title": "Redisclosure 1",
        "body": {
          "type": "text",
          "value": "First redisclosure message."
        },
        "input": {
          "type": "none",
          "options": []
        },
        "btn_confirm": {
          "label": "Ok"
        },
        "btn_reject": {
          "label": "",
          "visible": false
        }
      },
      "type": "Prompt" // This allows custom questions to be asked to the user.***
    },
    "Redisclosure2": {
      "actions": {
          "confirm": true,
          "reject": false
      },
      "attestationMetadata": {
        "confirm": {
          "attested_patient": true,
          "modified_consent": true
        }
      },
      "content": {
        "title": "Redisclosure 2",
        "body": {
          "type": "text",
          "value": "Second redisclosure message."
        },
        "input": {
          "type": "none",
          "options": []
        },
        "btn_confirm": {
          "label": "Ok"
        },
        "btn_reject": {
          "label": "",
          "visible": false
        }
      },
      "type": "Prompt"
    },
    "BreakTheGlassGroupCheck": {
      "actions": {
        "confirm": "PatientConsentEmergency",
        "reject": "IsPatientMinor"
      },
      "groups": ["BreakTheGlass"],
      "type": "GroupCheck"
    },
    "PatientConsentEmergency": {
      "actions": {
        "confirm": "BreakTheGlassPrompt",
        "reject": "IsPatientMinor"
      },
      "attestationMetadata": {
        "confirm": {
          "broke_glass": true,
          "view_bh": true
        },
        "reject": {
          "broke_glass": false,
          "view_bh": false
        }
      },
      "compare": {
        "operator": "OR",
        "query": "()mpid:{mpid}",
        "value": ["U", "E"],
        "field": "consent",
        "store": "Consent"
      },
      "type": "QueryCheck"
    },
    "BreakTheGlassPrompt": {
      "actions": {
        "confirm": "Redisclosure1",
        "reject": "IsPatientMinor"
      },
      "content": {
        "title": "Break the Glass",
        "body": {
          "type": "text",
          "value": "Do you want to break the glass?"
        },
        "input": {
          "type": "none",
          "options": []
        },
        "btn_confirm": {
          "label": "Yes"
        },
        "btn_reject": {
          "label": "No",
          "visible": true
        }
      },
      "type": "Prompt"
    },
    "IsPatientMinor": {
      "actions": {
        "confirm": "ParentalConsentGroup",
        "reject": false
      },
      "compare": {
        "operator": "==",
        "query": "()mpid:{mpid} ()d.patient_date_of_birth:[TODAY-18Y TO TODAY]",
        "value": "1",
        "field": "{count}",
        "store": "1101"
      },
      "type": "QueryCheck"
    },
    "ParentalConsentGroup": {
      "actions": {
        "confirm": "ParentalConsentPrompt",
        "reject": false
      },
      "groups": ["ParentalConsentOverride"],
      "type": "GroupCheck"
    },
    "ParentalConsentPrompt": {
      "actions": {
        "confirm": "Redisclosure1",
        "reject": false
      },
      "content": {
        "title": "Parental Consent Override",
        "body": {
          "type": "text",
          "value": "Do you want to access the records via Parental Consent Override?"
        },
        "input": {
          "type": "none",
          "options": []
        },
        "btn_confirm": {
          "label": "Yes"
        },
        "btn_reject": {
          "label": "No",
          "visible": true
        }
      },
      "type": "Prompt"
    }
  }
}

*The properties being used can be whatever you wish to assign them. However, you must assign a property to use. If you try to use a property that is not set up in the initialAttestationMetadata block, it will return an error. The attestation Metadata values get stored in the attestation record so can be used in reports.

**The QueryCheck block allows a custom query to be executed. The results of the query is then compared to "value" using the "operator". Query property accepts special runtime resolution variables {mpid} and {user}, along with {facility} which resolves to {facility} portion of the user's facility_{facility} group. The order of comparison is as follows: {queryResult} {operator} {configValue}. If true, action.confirm is automatically executed. If false, action.reject is automatically executed.

***This prompt allows custom questions to be asked to the user. Configuration allows placement of a text area, radio, or checkbox options for the user to enter their answer. None may be used as the input to present the user with a message that they can accept or confirm. Regardless of the user's answer, if they click btn_confirm, the action.confirm executes, and the answer is sent to the server to be logged.

GUIDs and SUIDs

These are unique identifiers. They collect a list of all of the unique values that have been encountered within a specified field. SUID (Store Unique Identifier) fields track the unique values for this field within a store. GUID (Global Unique Identifier) fields track the unique values for this field across all stores. GUID fields are most commonly used with a corresponding quicktable to enable field value centric reports or sets (e.g. patient centric reports).

Adding SUID/GUID fields:

1. In the Navigation menu, click Configuration.

2. Go to parsetable.d/IMAT.xml or alternatively vim /opt/search/appliance5/conf/parsetable.d/IMAT.xml.

3. Add

4. MarkupMarkup

   <field name='patient_id' map='guid'> # or use map='suid' 
       <tag name='patient_id'>
   </field>

5. Make a corresponding entry to the QuickTables, qx.default.def or vim /opt/search/appliance5/conf/qx.default.def.

6. If using SUIDs, add the value to the associated quicktable for each store that this field could occur: for example, qx.0.def. The table should contain the following changes:

   [fieldname str StrTable=guid]

   A specific example is found below. This example is adding the change to the patient_id field:

   patient_id str StrTable=guid

7. Click save.

8. Restart the search server by contacting professional services. All changes take effect from this point forward, but the changes are not retroactive.

VHR Configuration

VHR comes with five configurable files. Some of the elements within the files are not configurable and should not be changed. If there is any question if information can be changed, contact professional services. See here for more information.