Define Combinations of Triggers, Rules, and Cards

The InterSystems® Healthcare Action Engine configuration application allows you to construct synchronous HL7® CDS Hooks services by defining and combining a series of components:

This page describes how to access the configuration application and how to configure each component.

The configuration application also provides access to other configuration options on the Settings page.

Access the Configuration Application

You can access the Healthcare Action Engine configuration application in a web browser by navigating to a URL with the following form:

<baseURL>/csp/healthshare/<haeNamespace>/hseds/ui/hs-eds-config-ui/index.html

where <baseURL> represents the fully-qualified URL for the instance which hosts the Healthcare Action Engine (including the hostname, port number, and URL prefix as needed), and <haeNamespace> represents the name of your HAE namespace. You may wish to bookmark this URL for easy access.

Alternatively, you can access the Healthcare Action Engine configuration application through the Management Portal by performing the following steps:

Log in to the Management Portal for your Healthcare Action Engine instance.
Switch to your Healthcare Action Engine namespaceOpens in a new tab.

Note:

In the current version of the Healthcare Action Engine, if you have configured HAE as part of a HealthShare federation, you cannot access the Healthcare Action Engine namespace from the HealthShare menu from a production namespace (such as your Registry namespace). Switch to a default system namespace (such as HSLIB) or access the configuration applications directly using their respective URLs.
Select your Healthcare Action Engine namespace from the list.
From the menu, select Healthcare Action Engine. (You can also access the CDS Hooks Connection Broker configuration page and the FHIR package configuration page from this menu.)

Important:

When you access the Healthcare Action Engine configuration application through the Management Portal, an authenticated session within the HAE configuration application does not time out until your Management Portal session does. By default, the timeout parameter for the Management Portal is significantly longer. Therefore, under these conditions the authenticated session within the HAE configuration application may remain active and valid for subsequent use for an extended length of time, even if users navigate away from the page and then return.

To guarantee system security and the privacy of privileged information, navigate to the HAE configuration application directly (using the URL) whenever possible. If you must access the HAE configuration application through the Management Portal, be sure to log out of the Management Portal so that your session within the HAE configuration application can expire according to the timeout parameter specified within HAE.

Triggers

Triggers are initial conditions within the client application that, when met, can initiate the evaluation of one or more rules. Triggers are analogous to “hooks” within the CDS Hooks specification (see https://cds-hooks.hl7.org/2.0/#hooksOpens in a new tab).

For example:

the patient-view trigger allows you to define a service which the client application can invoke whenever a provider using the client application accesses a patient’s chart.
the order-select trigger allows you to define a service which the client application can invoke whenever a provider using the client application selects (but has not yet signed) an order for a patient.

To view information about the synchronous triggers available, access the Triggers page from the Synchronous section of the configuration application’s navigation menu (Synchronous > Triggers).

The Healthcare Action Engine supplies you with pre-configured triggers you can use to build your notification services. In this version of the Healthcare Action Engine, you cannot create any new triggers.

Rules

Rule Workflow

Rules are the core evaluation component of a synchronous Healthcare Action Engine service. Rules apply conditional logic to data about the context—including FHIR resource data from the client application’s FHIR repository— in order to determine what response (if any) the service sends to the client application.

HAE evaluates a rule when—after the occurrence of the trigger event—the client application sends a request invoking the associated service.

Rules are stored in the Rule Library, and are accessed by the Rule Launcher, which forwards rules to the Rules Engine for evaluation.

To view information about the synchronous rules in the Rule Library, access the Rules page from the Synchronous section of the configuration application’s navigation menu (Synchronous > Rules). When you select one of the rule entries in the Rules table, it expands to display the cards currently associated with that rule.

Defining a new rule consists of two steps:

Create the rule by specifying its metadata within the configuration application.
Construct the rule’s evaluation logic using the Healthcare Action Engine Rule Editor.

Create a Rule

Creating the rule begins with specifying its metadata in the configuration application: its name, description, and the trigger associated with the rule.

To create a new rule:

Go to the configuration application.
Select Rules.
Select +New Rule, and enter values for the following fields:
- Rule Name — a name for your rule.
- Description — a user-friendly text description for your rule.
- Topic — a user-friendly label for your rule. You can sort rules by topic for easier categorization and search.
- Trigger — the trigger associated with your rule. When this trigger is activated, its associated rules are evaluated.
- Rule Engine — the rule engine associated with this rule. In the current version of the Healthcare Action Engine only the InterSystems IRIS FHIR Health rule engine is supported.
- Business Rule Package Name — the class package that the rule evaluation logic will be created in. By default, this field has a value of DecisionSupport. It is recommended you do not edit this value.
- FHIR Package — a FHIR packageOpens in a new tab. This determines the set of functionality to be expected from any FHIR server that the rule communicates with. The Healthcare Action Engine provides several packages for STU3Opens in a new tab, R4Opens in a new tab, and US CoreOpens in a new tab by default.
- Publication Status — see Update a Rule’s Publication Status.
Select Save to save your rule.
In the Edit Rule modal dialog which appears, select Open in Rule Editor if you want to create the evaluation logic for the rule now using the Healthcare Action Engine Rule Editor. Otherwise, select Return to Rules Table to return to the configuration application.

Note:

When you select Open in Rule Editor, Healthcare Action Engine attempts to open the Rule Editor in a new web browser tab. If you have a popup blocker enabled, you may need to configure it to allow Healthcare Action Engine to do so.

If you are creating a rule as the first step of creating a rule function, continue here.

Rule Inputs

A rule input specifies data that must be retrieved from the client application’s FHIR repository to evaluate a rule.

HAE creates and maintains rule inputs when you use the HAE Rule Editor to build expressions which involve FHIR queries.

See Configuring Rule Inputs for information on how to modify an existing rule input.

Update a Rule’s Publication Status

The publication status allows you to control how HAE makes a rule available to client applications as part of a CDS Hooks service. A rule can have one of three publication statuses:

Draft — a draft rule’s service is available to client applications at its service endpoint, but it is not listed as part of the discovery response. This is the default publication status for a new rule.
Active — an active rule’s service is exposed at both the service endpoint and discovery endpoint.
Retired — a retired rule is available to neither the service endpoint nor the discovery endpoint.

To update the publication status of a rule:

Go to the configuration application.
Select Rules.
Select the icon next to the rule you wish to edit.
For Publication Status, select the drop-down menu and choose from Draft, Active, and Retired.
Select Save to save your rule.

Cards

Card Workflow

A diagram depicting how the service handler retrieves a card from the card library as directed by the rule launcher and then

A card is the one of the two types of output a rule can conditionally include in a service response. A card provides information, a suggestion, or a warning to the user of the client application.

To configure a rule to return a card under a certain evaluation condition, create the card in the configuration application, and then edit the rule in the Rule Editor.

Create a Card

Note:

Required fields are marked with a red asterisk (*) in the configuration application.

Refer to the CDS Hooks specification for more information regarding the card attributes referenced below: https://cds-hooks.hl7.org/2.0/#card-attributesOpens in a new tab.

To create a card:

Go to the configuration application.
Select Cards.
Select +New Card
Enter values for the following fields:
- Under Card Information:
  - Name — a name for your card.
  - Summary — a one sentence summary message for display to clinicians. Your entry must be less than 140 characters.
  - Details — additional detailed information for the clinician. This field is optional.
  - Indicator — this field denotes the “urgency” of the card. The options, in increasing urgency, are info, warning, and critical.
- Under Source:
  - Label — a short, human-readable label to display for the source of information displayed on this card.
  - URL — a URL to load when a user clicks on this link to learn more about the organization or data set that provided the information on this card.
  - Icon URL — a URL to an icon for the source of this card.
  - Topic — a topic provides a high-level categorization of the card that can be useful for filtering, searching, or ordered display of related cards in the client UI. You can select the Add Topic button to add a topic, after which you must enter values for the following fields:
    - Code — the code for what is being represented by this topic.
    - System — a URL to the code system being used for topics. This field is optional.
    - Display Text — a short label to display for this topic. This field is optional.
    You can add multiple topics to a single card. To delete a topic, select the trash bin icon to the upper right of that topic.
- You can additionally configure the card to include Suggestions, Override Reasons, and Links, as discussed below.
Select Save to save your card.

Add Suggestions to a Card

In the context of creating or editing a card, you can select the +Add Suggestion button to add a suggestion. A suggestion is a proposed course of action for the provider who is using the client application, based on the contents of the card.

If you wish to add one or more suggestions to the card, you must select an option for the following field:

Selection Behavior — select the radio button that corresponds to how many suggestions the clinician may choose from this card.

Additionally, for each suggestion you wish to add, you must enter values for the following fields:

Label — a description of the suggestion.
This suggestion is recommended — select this checkbox if you have added multiple suggestions to this card and wish to prioritize this specific suggestion.
You can add an action to the card by selecting the +Add Action button.
If you would like to add an action to a suggestion, provide the following information:
- Action Type — the type of action being performed. In this version of Healthcare Action Engine, only the Create action is available.
- Resource — the new FHIR resource to be created if this suggestion is accepted
- Description — a short description of this action.
- Extension — an optional JSON object to include as part of this action, as an "extension" element. For example, the davinci-crd.if-none-exist extension allows for the conditional creation of a resource if it does not already exist. To implement the conditional creation of a FOOBAR Questionnaire resource using this extension, you might provide the following in the Extension field:
```
{"davinci-crd.if-none-exist": "url=http://fhirserver.myhsorg.com/Questionnaire/FOOBAR&version=1"}
```
Refer to the CDS Hooks specification for more information about actions: https://cds-hooks.hl7.org/2.0/#actionOpens in a new tab.

Add Override Reasons to a Card

In the context of creating or editing a card, you can select the +Add Override Reason button to add an override reason. An override reason is a codified reason that a client application’s end user may select as their reason for rejecting the advice presented in the card.

If you wish to add one or more override reasons to the card, you must define the following values for each reason:

Code — the code for what is being represented by this override reason.
System — a URL to the code system being used for override reasons. This field is optional.
Display Text — a short label to display for this override reason. This field is optional.

You can add multiple override reasons to a single card. To delete an override reason, select the trash bin icon to the upper right of the override reason.

Add Links to a Card

In the context of creating or editing a card, you can select the Add Link button to add a link. A link is a URL to information which is relevant for the provider who receives the card.

If you wish to add one or more links to the card, you must define the following values for each link:

Under Links:

Label — a label to display for this link.
URL — the URL to load when a user selects this link.
Type of URL — select the radio button that corresponds to the type of URL supplied. There are two possible values:
- Absolute — this indicates that the URL is absolute and should be treated as such.
- SMART — this indicates that the URL is a SMART application launch URL.

You can add multiple links to a single card. To delete a link, select the trash bin icon to the upper right of that link.

Insert Dynamic Information into a Card

Using custom-defined tokens, the content of a card can also include contextual information which is dynamically determined at the time of rule execution. To use this feature, it is necessary to modify the associated rule as follows:

Using a supported IDE, open the rule definition class for the rule which is associated with the card. (The HAE Rule Editor cannot create dynamic card content at this time.)
Edit the BPL rule definition so that it includes a private variable which defines a mapping object in JSON format. This JSON object should assign a token key to each value that you want to include in the card. In the example below, an <assign> statement sets the value of a variable named @TokenMapJSON so that it maps the key patientGivenName onto the patient’s given name (retrieved data included within the patient-view trigger):
```
<assign property="@TokenMapJSON" value='"{myPatientName:"""_MyRuleTriggerDataPatient.{name(1).given(1)}_"""}"'></assign>
```
If the patient’s given name is Fred, the JSON text of this token map at evaluation time would be {patientGivenName:"Fred"}.
Within the rule’s <return> statement, provide the JSON object as the fifth parameter of the SerializeVals function. Continuing the preceding example:
```
<return>Assist.SerializeVals("#ReturnValsSpec","pAuthCard","some details","info",@TokenMapJSON)</return>
```
Save and compile the rule definition class.
Finally, edit the card template within HAE’s card editor. In each location where you want to incorporate one of the values you have made available within the token map, include the token key surrounded by double braces, as follows: {{tokenKey}}. Using the preceding example, the summary field for the card template which is associated with the modified rule can now specify:
```
This card concerns your patient, {{patientGivenName}}.
```
Tokens are replaced with their values when the Healthcare Action Engine generates the card from the card template, prior to returning the card to the client application.

Note that there are two special reserved token names that card templates can include: {{today}} and {{now}}. These tokens are automatically replaced with, respectively, the current date and the current time. It is not necessary to define them in a token map variable. These predefined tokens also support the use of time offsets—for example, {{today + 5 days}}.

Actions

Instead of a card, a rule can conditionally provide a list of one or more system actions to include in a service response. System actions can initiate a change on the client application’s associated FHIR server—creating, updating, or deleting a resource. Refer to the CDS Hooks specification for more information about system actions: https://cds-hooks.org/specification/current/#system-actionOpens in a new tab.

The configuration application’s Actions page lists the system action lists defined within the Healthcare Action Engine. Select the Actions tab Actions tab with gear icon to access the configuration application’s Actions page, which provides a table of the system action lists currently defined within the Healthcare Action Engine. Use this page to create or edit system actions lists. To configure a rule so that it returns the system actions list, edit the rule in the Rule Editor.

Create or Edit a System Actions List

To create or edit a system actions list using the System Actions List Builder, perform the following steps:

Go to the configuration application.
Select Actions.
To create a new system actions list, select +New System Actions List. To edit an existing system actions list, select the edit icon for the system action list’s row in the System Actions table. Both actions open the System Actions List Builder.
Enter or edit values for the following metadata fields:
- Name — a name which can identify this list of system actions within the Healthcare Action Engine.
- Description — a brief description of the system actions list. This entry must be less than 140 characters.
Define the actions in the system action list.
1. Add a new action to the system actions list by selecting the +Add Action button.
2. Actions in a system actions list are defined in the same way as a card’s suggested actions are. For each action in the system actions list, specify the following:
- Action Type — the type of operation the action performs on the FHIR server (create, update, or delete).
  
  Note:
  
  In this version of the Healthcare Action Engine, only the create action type is supported.
- Resource — the FHIR resource on which the action will be performed
- Description — a brief description of the action, which will be provided to the client as part of the action object.
- Extension — an optional JSON object to include as part of this action, as an "extension" element. For example, the davinci-crd.if-none-exist extension allows for the conditional creation of a resource if it does not already exist. To implement the conditional creation of a FOOBAR Questionnaire resource using this extension, you might provide the following in the Extension field:
```
{"davinci-crd.if-none-exist": "url=http://fhirserver.myhsorg.com/Questionnaire/FOOBAR&version=1"}
```
Optional: select JSON Preview to open the JSON Preview pane. This pane allows you to review how the system actions list you have defined will be structured when it is delivered as part of a service response’s JSON payload.
Select Save to save your system actions list.

Create Rules to Evaluate Conditions Using the Rule Editor

Introduction to Building Synchronous CDS Hooks Services