Configuration

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

Click on image to zoom

Creating a New File

Follow these steps:

1. Click add_circle.
2. Choose the file type:
   • Taxonomy File via Field Name.
   • Taxonomy File via Store.
   • QuickTable File.
3. Choose the field name or enter the store, depending on your choice in Step 1.
4. The name automatically generates, you cannot change it.
5. Click Create.

Click on image to zoom

Using Configuration

Each configuration change requires, at the very minimum, the three steps below. If more steps are needed, additional information is given with the configuration instructions.

1. Find the file from the Choose a file drop-down list.
2. Make the change or changes.
3. Press save or use the keyboard shortcut ctrl+S (PC) or cmd+S (Mac).

Searching Files

1. Click on the file from the file list.
2. Click anywhere in the text area.
3. Press find_in_page, or ctrl+F (PC) or cmd+F (Mac) on your keyboard to search for a keyword.
4. Click Enter on your keyboard to cycle though all the hits for your search.

If you click on a word in the editor, all occurrences of that word are highlighted in yellow.

Reloading Files

Clicking restore_page without saving the file reloads the file to the original settings.

Enabling Search Authentication

You can require users to log in to the search interface. This can protect your critical data from being seen by individuals who have no legitimate reason to access the data. However, if you enable this option, you take on the responsibility of managing user accounts for everyone who needs access to the data.

1. In the Navigation menu, click Configuration, then select search-ui.ini from the menu.
2. Set the require_query_authentication parameter to True. To disable this feature, set the parameter to False.
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.

Enabling Collections

Collections allow you to give groups access to documents based on the file path.

1. In the Navigation menu, click Configuration, then select search-ui.ini from the menu.
2. Set the enable_collections parameter to True. To disable this feature, set the parameter to False.
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 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. 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.

Creating New Search Stores

1. In the Navigation menu, click Configuration, then select SearchServer.conf from the menu.
2. Locate the lines that list the spaces. They look something like this:
   

   space-1 = Records
   space-2 = Labs
   space-3 = ADTs

3. At the end of the list, type the new store and store name, e.g. space-32 = SearchStoreName. All alphanumeric characters are allowed.
4. Locate the line job-cgi = commitindex=2&periodsec=90, and add an incremented line for the new search store; for example, job-cgi = commitindex=3&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 SearchServer.conf 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 {}.

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

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.

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 SearchServer.conf.
2. Locate exclude-spaces.
3. Create a comma-separated list of all stores you want excluded from searches.

4. Specify default search spaces to be included and excluded (used when no search space is specified in the query)
   
   # if include-spaces is absent, the default is all minus the exclude-spaces list
   # exclude-spaces = 2,3
   
   exclude-spaces = 50,51,52,53,54,63,64,1000,1002,1100,1101,1102,1103,1110,1120,1130,2016,2017,2018,2019,2020,2021,2022,2023,2024,2025
   

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.

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.

Configuring the Usage Log

The search server saves information on each user as he or she uses the server. Because this information is logged, it is possible to search usage log entries in detail. The searchable logs provide information on who has searched, what has been searched, and when it has been searched. Other collected data includes URLs, clients, HTTP methods, etc.

Turning On and Off Usage Log Auditing

1. Select one of these files from Choose a file:
   • searchserver-ui.ini
   • search-ui.ini
   • admin-portal.ini
2. Scroll down the script until usage_logs = True is found.
3. Make sure it reads True to record usage logs. Change it to False if usage logs should not be recorded; however, not recording logs is not recommended.
4. Repeat steps 1 through 3 until all three files are configured.
5. Click save.

Changing the Usage Log Level

The level settings determine how much information is recorded. By default, the level is set to INFO. The lower the level of tracking is set, the more hits are returned with the usage log. The levels available from lowest to highest priority are DEBUG, INFO, WARNING, ERROR, and CRITICAL. Debug is the lowest level and therefore returns the most hits because it collects all the data from debug to critical. If only critical is chosen, the other four are not searchable.

It is possible to change the level of logs recorded; however, because almost all entries are recorded on the INFO level, the need to change these levels is minimal and should not be done under most circumstances.

Below are steps to change the level of recorded entries: 

1. While still in the files above, locate the Logging configuration section.

2. # Logging configuration
   [loggers]
   keys = root, routes, searchserverui, usage, gunicorn.access
   ...
   [logger_root]
   level = INFO
   handlers = console

   Note:

   Capitalization of the value is important; make sure each value is in all capital letters.
3. Make all the level changes necessary for each section.
4. Click save.
5. Repeat for each configuration file.

Session Handler Timeout

Adjusting the timeout in the session handler can increase the amount of time a user has before he or she is logged out. For instance, if most users have timeout session of 15 minutes, but the report writers find that it is too short of time and they are timed out before they can finish writing the report, then it is possible to create a group for only those users to have a longer period before their session times out.

To change the timeout length for a specific group, follow the steps below. Remember that correct json syntax must be used.

1. Find the timeout length in the who.ini file. Leave the number as is, but you will need to figure out how many minutes this converts to in Step 5.
2. Go to Admin Configuration.
3. Locate role-properties.json.
4. Enter the group name in the "role" property.
5. Figure out the multiplier for the "sessionLengthMultiplier"property. To do this, determine the amount of time you would like the group to have before the session times out; subtract five minutes from the default timeout set in the who.ini file (after you have converted it to minutes); and then figure out the multiplier. See the example below. The default is 20 minutes and the administrator would like the group to have 60 minutes.
   
   

   (20 - 5) * x = 60
   x = 60/15
   x = 4

   Whole numbers must be used, no decimals are allowed.
6. Your code should now look like this:

7. [
       {
           "role": "LongerTimeoutGroup",
           "sessionLengthMultiplier": 4
       }
   ]
   

8. Repeat for each group you'd like to change, adding each group in a new block surrounded by braces and separated by a comma.
9. Click save.
10. Contact professional services to apply your changes to the server.

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.

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

5. Click save.
6. 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. <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:

7. [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

8. Click save.
9. 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.