Rules Engine Admin GUI Functional Spec

Summary

An administration gui will be added to OpenEMR for the purpose of managing the configuration of the newly contributed rules engine. The functions supported by the gui are the browsing, viewing of details, adding, editing, and deleting CQM and reminder rules. It will be accessible from a new Administration -> Rules left nav entry. Clicking on this nav entry will produce the Browse Rules page, which is the entry point into the gui.

Under advisement from Brady Miller, CQM/ACM rules will be neither editable nor addable until CQE itself is more properly understood and better supported by the rules engine:

"I'd rec not even allowing actual modification of the CQM/ACM rules (just like not allowing in patient specific gui), since this is standardized, complicated, and not yet completed."

CQM/ACM rules will be visible from the browse rules page, and their details are be retrieve via the Rule Details page.

Browse Rules

The browse rules page will permit users to add a new rule, or view the details of any existing rules in the system.

• Clicking on any existing rule will produce a detailed view of the rule, where further action can be taken.
• The rules may be sorted by Name and Type (CQE, Reminder) of rule.
• Clicking on the 'add' button will produce the add new rule interface.

Rules Detail

The Rules Detail page will permit users to view and edit rule details such as title, reminder intervals (if applicable), actions, demographic filters, and clinical targets. Users will also be able to remove the rule from the system from this page.

Adding Rule

To add a rule, the gui will prompt the user for the rule type (CQM or Reminder) and the rule title. After selecting the rule type, the gui will invite the user to save the rule, or cancel rule creation.

If the rule is of a Reminder type, the system will additionally prompt for Clinical and Patient reminder periods. Users will be required to specify the amount of time elapsed until the reminder becomes a warning or is passed due. This period is specified in weeks or months.

If the rule is of a CQM type, the system will indicate that adding CQM rules are not yet supported.

If the user cancels rule creation, they are navigated back to the Browse Rules page. If they save the rule, they are taken to the Rule Details page, where most of the sections will be empty.

Saving the rule will create an entry in the clinical_rules table with the format rule_*, where '*' will be the next number in a sequence (most likely the current size of the clinical_rules table plus 1). The number will be used as in the list_options table for ancillary items relating to that rule, such as rule_action.item entries.

Editing Rules

To edit a rule, users navigate to the rule's Detail page, where (edit) buttons on the individual sections (filters, targets, etc.) may be invoked to bring up the same view as when adding to those sections, except that the values are prefilled with the previously provided values. Clicking (cancel) on any section will return the user back to the Rule Details page, as will any successful (save) invocation.

Adding demographic filters

Users may add demographic filter criteria to a rule from the Rules Detail page. Clicking on the 'Add' button for demographic filter criteria will navigate the user to a new page displaying the different types of criteria that may be added.

The starred items indicate those types of criteria which may be added multiple times to the same rule. The others may only be added once, and will be excluded from the list if an entry of that type is already present in the rule. Clicking cancel will navigate the user back to the Rules Detail page; clicking on any criteria will refresh the page with the interface for constructing that criteria.

Demographic filter: Age

Pictured below is the user interface for adding Age criteria. In edit mode, the input field is pre-filled from the rule_filter table.

The user will be prompted to enter:

• The maximum patient age in months or years
• Whether or not meeting the criteria is optional
• Whether or not triggering this rule based on meeting or not meeting this criteria (inclusion vs. exclusion)

All fields are required, enforced when the user clicks (save).

Demographic filter: Sex

The sex demographic filter prompts users to enter:

• Patient sex
• Whether or not meeting the criteria is optional
• Whether or not triggering this rule based on meeting or not meeting this criteria (inclusion vs. exclusion)

All fields are required, enforced when the user clicks (save).

Demographic filters: Diagnosis, Medical Issues, Medications, Allergy, Surgery

Clicking on Diagnosis, Medical Issues, Medications, Allergy, or Surgery items when adding demographic filters produces the user interfaces for these criteria. Edit mode will be the same, but pre-filled with the previously saved entry. The system will compare these values against the lists table when evaluating patients against the rule. All fields are required, enforced when the user clicks (save).

Common to these criteria are the two questions relating to inclusion/exclusion, as well as required/optional.

For the Diagnosis criteria, the ui is comprised of a typeahead search textbox, which produces a dropdown with the top 5 results matching the code or code text of ICD9 entries in the code table. The field is freetext, and any value may be entered here; if one of the values in the dropdown are chosen, the value is entered into the textbox.

The remaining criteria are simple free-text entry fields.

Demographic filter: Lifestyle

Adding or editing the Lifestyle criteria produces a ui permitting the user to build criteria compared against history_data table columns when filtering patients against the rule.

The user must select a lifestyle measure, and indicate whether or not an exact match must be made against a specified value, or any entry other than empty, in order to trigger the rule. The two questions relating to inclusion/exclusion, as well as required/optional, are also required.

Demographic filter: Custom

Users may build custom filter criteria sourced from either the rows in the rule_patient_data table, or some other table and column in the system.

Selecting New will source from rule_patient_data, and Existing will source the criteria from some other table and column in the system.

Sourcing from rule_patient_data (New)

Specifying that a filter criteria has a source type of 'New' indicates that the rules engine will inspect patient data marked with the category and item entered in the interface below for completion or non completion. The frequency of required matches is also configurable. All fields are required, and enforced on 'save'.

Sourcing from some other table and custom (Existing)

When filter criteria has the source type 'Existing', the system will prompt the user to specify an openemr table and column which the rules engine will inspect when filtering patients. Selecting a table will dynamically alter the available columns. Note that foreign key relationships are not decoded. The value to be matched and the logical comparator must be specified. The frequency of required matches is also configurable. All fields are required, and enforced on 'save'.

Rule Actions

One or more rule actions may be assigned to any given rule. These may be added to a rule from its Detail page.

The category dropdown may be a static list which maps to list_option.title where list_option.category is one of:

• act_cat_assess
• act_cat_edu
• act_cat_exam
• act_cat_inter
• act_cat_measure
• act_cat_remind
• act_cat_treat

Alternatively these could be sourced from list_option.title where category starts with 'act_cat%'.

The Title field is a dropdown whose initial contents are existing matches in the rule_action.item table (real names coming from list_options), which are filtered down to what matches what the user is currently typing. If there are no matches to what the user has typed so far, and the user elects to save, Title will be persisted as a new list_options row with the list_id set to the chosen category, list_options.title set to the inputed title, the sequence autoincremented by 10 from the most recently entered rule action, and the option_id set to the sequence portion of the rule id.

If an existing category/item pair is selected, and the user saves, an entry in the rule_action table will be created with that existing category and item.

The reminder link and message are optional, and the custom flag is required.

Clinic target filters

Clinic target filters may be added to an existing rule from the rules detail page by clicking 'add', which will prompt the user for which type of filter to add. This page looks identical to the demographics filter page, except that only two items are presented: Lifestyle and Custom.

The Lifestyle and Custom add/edit interfaces for clinical targets is identical to the one for demographic filters, except for the addition of an optional Frequency dropdown, inviting the user to select Month, Year, or Flu Season.