Skip to main content

Deliver Asynchronous Notifications with the Healthcare Action Engine

You can configure the Healthcare Action Engine to deliver asynchronous notifications as well as synchronous ones. Whereas synchronous HAE services communicate with a client application in real-time during a user’s session, an asynchronous HAE service detects a particular change to a data source (for example, the receipt of an HL7® V2 ADT message for a patient) and transmits a message to the appropriate party (for example, the patient’s primary care physician) through a contact system such as email.

Caution:

This version of the HealthShare® Healthcare Action Engine (HAE) includes asynchronous notification functionality for limited customer testing only. Further development may substantively change how asynchronous notifications are implemented. When used only for testing, there is no potential for patient harm and so this experimental feature is not yet included in the scope of clinical safety assessment and publications. Use of this experimental feature for any purpose other than product testing is prohibited.

Note:

Currently, asynchronous notifications require Healthcare Action Engine to be deployed alongside HealthShare Unified Care Record®Opens in a new tab 2023.1 or later.

This page describes the additional configuration steps which you must complete to enable HAE to deliver asynchronous notifications.

It then describes the process for creating and deploying an asynchronous notification service using the HAE configuration application. This workflow closely resembles the workflow for creating synchronous notifications; it consists of defining and combining a series of components, as follows:

  1. Choose what change to the data source will serve as a trigger event.

  2. Define a rule (or rules) to be evaluated when the trigger event occurs. A rule applies conditional logic to data about the context in order to determine what type of response (if any) HAE returns.

  3. Create a card for each type of response that you want HAE to send for a given rule.

  4. Specify how the Healthcare Action Engine responds for a given rule response by setting a notification policy. A notification policy consists of:

    1. a method for determining the recipient who will receive the notification.

    2. a message template. A message template determines how HAE formats information about the card and the trigger into a notification which is appropriate to a contact system (such as email)

Set Up an Events Feeder on Your Unified Care Record Instance

Healthcare Action Engine is a standalone component. To enable the Healthcare Action Engine to respond to events within your HealthShare Unified Care Record deployment, you must configure an HAE Events Feeder namespace and production within your HealthShare federation. The Events Feeder communicates with HAE as an external HTTP service whenever a trigger event occurs.

After you have set up your HAE instance, configure the HAE Events Feeder as follows:

  1. The HAE installation process automatically registers an HAE user account (HAE_Trigger) which the Events Feeder can use to authenticate its communications with HAE. For security, InterSystems recommends changing this account’s default password (HS_Services). To do so:

    1. From the HAE Management Portal, select System Administration > Security > Users > Go.

    2. On the Users page, select HAE_Trigger from the list to access the Edit User page.

    3. On the Edit User page, enter a new password. When you are finished, select Save.

  2. Within your HealthShare federation, install the HAE Events Feeder. To do so:

    1. If you have not already done so, install and configure a HealthShare instanceOpens in a new tab to host the Events Feeder as part of your HealthShare federation. Provide the license key which includes support for Healthcare Action Engine.

      Note:

      If your HealthShare federation is configured to share a single-sign on authentication system, you must install the Events Feeder on an instance which is part of this system. As a standalone component, the Healthcare Action Engine itself remains outside of the federated authentication system.

    2. From the Management Portal home page of this federated instance, select HealthShare.

    3. Select the Installer Wizard link.

    4. Select Configure Action Engine Events Feeder. This displays the Configuration dialog for the Healthcare Action Engine.

    5. Enter a name for the namespace in the Local Name field and press Tab. The Network Name field populates automatically. For example purposes, this guide uses the namespace AEFeeder.

    6. Select Save at the bottom of the page. Your configuration should now appear in the Defined Configurations table.

    7. In the row of the Defined Configurations table corresponding to your Event Feeder configuration, select Activate. This displays the Activate Configuration dialog.

    8. In the Activate Configuration dialog, select Start.

    9. When the window says Activation Done, select Close.

  3. To communicate with HAE, the Events Feeder must authenticate using the credentials for the HAE_Trigger user which HAE recognizes. Within the Events Feeder namespace (AEFeeder), create a Credentials profile to store the credentials for the HAE_Trigger user. To do so:

    1. Open the Management Portal of your Unified Care Record instance and switch to your Events Feeder namespace.

    2. Select Interoperability > Configure > Credentials.

    3. On the Credentials Viewer page, provide the credentials for the Healthcare Action Engine user you created, HAE_Trigger:

      • For both ID and User Name, enter HAE_Trigger.

      • For Password, enter the password for the HAE_Trigger user you specified in step 2.

    4. Select Save.

  4. Add a new HTTP service to the HealthShare Registry which uses the HAE_Trigger credentials to connect with the Healthcare Action Engine at its API endpoint. To do so:

    1. Open the Management Portal for an instance within your HealthShare federation and switch to the Registry namespace.

    2. Select HealthShare > Registry Management > Service Registry.

    3. Select the Add Service button.

    4. In the form that appears, define a service with the following details:

      • For Name, enter HAETriggerService<HAEinstance>, where <HAEinstance> is an optional identifier for your Healthcare Action Engine namespace.

      • For Service Type, select HTTP from the drop-down menu.

      • For Host, specify the hostname for your Healthcare Action Engine instance.

      • For Port, specify the web server port number for your Healthcare Action Engine instance. If you are using a web prefix to specify a unique URL for HAE, you do not need to provide a Port, but you must include that web prefix in the URL.

      • For URL, enter /csp/healthshare/<HAENamespace>/hseds/api, where <HAENamespace> is the name of your HAE namespace. If you are using a web prefix to specify a unique URL for HAE, include that web prefix in the URL in the following format: /<webPrefix>/csp/healthshare/<HAENamespace>/hseds/api.

      • For HTTPCredentialsConfig, select the HAE_Trigger credential profile from the drop-down menu.

    5. Select New to add the new service to the Service Registry.

  5. Ensure that the Events Feeder can communicate with an active HL7® FHIR® R4 endpointOpens in a new tab within your HealthShare federation using recognized credentials. To do so:

    1. Switch to the Events Feeder namespace and select Interoperability > Configure > Credentials.

    2. If you would like to use the default HS_Services credentials profile (with the default password HS_Services), ensure that this credential is listed in the Credentials Viewer. Alternatively, specify a new set of credentials by selecting the New button and filling out the form. For security, InterSystems recommends creating an alternative credentials profile.

    3. From the Management Portal home page within your Events Feeder namespace, select Interoperability > Configure > Production.

    4. Select the TriggerSender operation from the list of Operations.

    5. In the Settings tab of the details pane for this operation, locate the Credentials field in the Basic Settings section. Select the credentials profile you chose to use in step 7b.

    6. Switch to your Registry namespace and select HealthShare > Registry Management > Service Registry.

    7. On the Service Registry page, select HTTP as the Service Type from the drop-down menu. Select the entry for the service with the Name FHIR.Service.R4. Note that you may need to navigate between pages of results to locate this service.

    8. Locate the HTTPCredentialsConfig drop-down menu and select the same credentials profile which you specified for the TriggerSender operation in step 7e.

    9. Select Save.

  6. Start the HAE Events Feeder production. To do so:

    1. In the Management Portal for your HealthShare federation, switch to the HAE Events Feeder namespace and select Interoperability > Configure > Production.

    2. Select Start. Select OK to confirm, and then select OK again when startup is complete.

Upon startup, the HAE Events Feeder sends an initialization message to the Healthcare Action Engine. In response, HAE adds a set of default asynchronous triggers to the configuration application.

For sample implementations of asynchronous notification policies which use these triggers, install the Healthcare Action Engine demo after you have completed the preceding configurations steps. (The InstallDemo() method does not include this asynchronous demo data if the method is invoked before the Events Feeder’s initialization message.)

Define Triggers, Rules, and Cards

To create and deploy HAE asynchronous notification services, you must use the configuration application to define and combine a series of components. The first three components in the series—triggers, rules, and cards—are essentially the same for both synchronous and asynchronous notifications.

Triggers

For asynchronous services, triggers are events which take place within the information exchange system to which the Healthcare Action Engine is connected. An example of an asynchronous trigger would be the receipt of a new HL7® V2 ADT message. To view information about the asynchronous triggers available, access the Triggers page from the Asynchronous section of the navigation menu (Asynchronous > Triggers).

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

Set a Trigger’s Activation Status

On the Asynchronous > Triggers page, you can toggle whether an asynchronous trigger is active or inactive by selecting the edit icon (pencil) icon for the trigger and then selecting the desired status from the Set Activation Status drop-down menu. You can choose from the following statuses:

  • Active — the Healthcare Action Engine processes events for the trigger, and evaluates any active rules which are associated with the trigger.

  • Inactive — the Healthcare Action Engine does not process events for the trigger.

Rules

An asynchronous rule is activated when the Events Feeder service connected to the data source notifies HAE’s trigger endpoint that an asynchronous trigger event has occurred.

Other than that, the process for defining an asynchronous rule is the same as defining a synchronous one:

  1. Create the rule by specifying its metadata within the configuration application.

  2. Construct the rule’s evaluation logic using the Rule Editor.

Cards

For asynchronous notifications, a card provides the information which HAE then formats into a message based on a notification policy’s message template.

The process for defining a card as part of an asynchronous service is the same as defining a card as part of a synchronous one:

  1. Create a card in the configuration application.

  2. Reference the card when you construct a rule’s logic in the Rule Editor.

Recipients

Currently, the Healthcare Action Engine only supports a group-based method for determining who receives asynchronous notifications.

The HAE configuration application’s Asynchronous > Recipients tab allows you to review the Groups table, which contains information about the contacts who are currently configured to receive asynchronous notifications. A group of patients is associated with a contact address for the group’s managing entity (such as a clinician). If the evaluation of an asynchronous rule returns a card in response to a trigger which involves a particular patient, the Healthcare Action Engine can send a custom notification to the contact for any group which includes that patient.

The Groups table includes the following information:

  • Name: a descriptive label for the group, if one was provided

  • ID: the identifier for the group FHIR resource in your source repository

  • Managing Entity: the name of the managing entity for the group, if one was provided

  • Contact System: the contact point system for the group’s contact address (for example, email)

  • Contact Information: the number or address where the Healthcare Action Engine sends notifications for the group

  • Last Updated: the date and time when information about this group was most recently imported

  • View Members: a button which displays a modal dialog box containing a list of identifiers for the patients in the group

The Groups table also provides a search field where you can filter the contents by keyword. Although the table itself does not include the patient identifiers for group members, you can use this search field to find groups containing a patient by entering the patient identifier.

To specify groups, import them from a .txt or .csv file as described in the next section.

Important:

These records of notification recipients and their associated patient groups are maintained as FHIR resources in a local repository, within the HAE namespace. This local repository never stores clinical data.

However, because the local HAE repository for these recipients does not store any clinical data, the identifiers of the patients and groups stored in this local record must match the identifiers for these entities within the FHIR repositories where clinical data is stored. Otherwise, the Healthcare Action Engine cannot identify the patient associated with the trigger event as a member of a notification group.

Import Groups from a .txt or .csv File

To maintain the record of notification recipients and the groups of patients associated with them, you must import a .csv or .txt file which contains this information into the Healthcare Action Engine. You must generate this file according to the specifications described in the next section. If you have installed and deployed the HAE demo production, the /Data directory for this production contains a template file illustrating the expected format.

To import a notification group file, perform the following steps:

  1. On the Recipients page, select the Import Groups button.

  2. Select Browse Local Files.

  3. Use the file upload window to select the .csv or .txt file containing the group information you want to import.

  4. Select Import. In the configuration application, a notification will display information about the information imported, as well as

Each import is a full logical replacement of the notification group information from the previous import. If a group is not included in the contents of a notification group file you import, the corresponding entry is removed from the Groups table and the contact recipient specified for that group no longer receives notifications for the set of patients specified as part of that group.

Note:

When an import removes a notification group, HAE deletes the group resource according to the FHIR specification for a delete interactionOpens in a new tab.

Expected Format of a Notification Group File

For HAE to parse information about your notification groups from a .csv file, the file must follow a specific format.

Each line in this file is a record which represents either a group or an individual patient who is a member of a group. To distinguish between the two, the first value of each record must be either GRP (for group) or MBR (for member).

Each patient record assigns the patient to the group whose record most closely precedes it. This version of the Healthcare Action Engine does not support assigning the same patient to multiple groups; each patient must be a member of one group exclusively.

In the example which follows, Susan Wong and Roberto Nogales are assigned to group 1001; Madeline Goldstein and Edna Richardson are assigned to group 1002.

GRP,1001,,,sms,2265553499
MBR,3992118,Wong,Susan
MBR,7641009,Nogales,Roberto
GRP,1002,,,email,drjones@email.org
MBR,6881653,Goldstein,Madeline
MBR,2223491,Richardson,Edna
GRP record

Each GRP record must occupy its own line, and must provide the following information about a group, in the following order:

GRP,<ID>,<group-name>,<contact-name>,<contact-type>,<contact-address>
<ID> Required. The identifier for the FHIR resource group in your source repository.
<group-name> Optional. A descriptive label for the group.
<contact-name> Optional. The name of the group’s contact person (or other managing entity).
<contact-type> Required. The medium of communication for the contact provided. This should be a valid member of the FHIR contact point system value set, such as phone or email.
<contact-address> Required. A contract address of the type specified by <contact-type>. For example: if <contact-type> is email, then this the email address.
MBR record

Each MBR record must occupy its own line, and must provide the following information about a patient, in the following order:

GRP,<pid>,<last-name>,<first-name>
<pid> Required. The identifier for the patient FHIR resource in your source repository.
<last-name> Optional. The last name of the patient.
<first-name> Optional. The first name of the patient.

Message Templates

When a notification policy is fulfilled, a message template provides instructions for how to construct a message appropriate to the contact system which the Healthcare Action Engine is using to send the notification.

The HAE configuration application’s Message Templates tab allows you to review the Delivery Message Templates table. The table provides metadata for existing message templates, including the date and time the message template was most recently modified (Date Modified) and the name of the user who most recently modified it (User Modified). It also provides a search field where you can filter the contents by keyword.

To create a new message template, selecting the New Message Template button.

To edit an existing message template, locate the entry for the message template in the Delivery Message Templates table and select the Edit edit icon (pencil) icon in the Actions column. To delete the message template, select the Delete An icon of a trash bin icon.

Create or Edit a Message Template

The Message Template Metadata Configuration page allows you to create a new message template or edit an existing one by specifying the following information using the form fields provided:

  • Message Template Name: a name identifying the message template.

  • Summary: a brief description of the message template.

  • Trigger Data Type: the data type of the resource associated with the trigger event for the notification. A message template can incorporate information about the trigger event itself; the trigger information available depends upon the data type of the trigger. This version of the Healthcare Action Engine only supports triggering asynchronous notifications based on encounters.

  • Contact System: the contact point system for the group’s contact address. This version of the Healthcare Action Engine only supports email.

  • Topic: an optional, user-friendly category for the message template. You can sort message templates by topic for easier sorting and search.

  • Template Text: the content of the message. Using the embedded text editor, you can edit the content of the message and modify how the content is formatted.

    The default content of a Template Text includes a set of token strings delimited with a double set of braces (that is, {{foo}}), alongside a brief description. You can include these token strings anywhere in your Template Text; upon execution of an asynchronous notification policy which uses this template, the Healthcare Action Engine dynamically replaces the token string with the associated value from the trigger event or the resulting card. For example, the Healthcare Action Engine replaces the token string {{Trigger-Patient-Name}} with the name of the patient that the notification is about.

When you are finished editing, select Save Template to save the message template. Select Cancel to discard your changes and return to the Message Templates page.

Notifications

The HAE configuration application’s Notifications tab allows you to review the Notification Policies table. This table summarizes all of the asynchronous notifications you have configured by binding together a trigger, a rule, and a card with a method to determine who receives the notification and specifications about the form the notification takes.

Each entry in the table represents a notification policy, and includes the following information:

  • Name: a descriptive label for the notification policy

  • Description: a short description of the notification policy

  • Topic: an optional, user-friendly label for the notification policy. Using topics, you can categorize your notification policies for easier sorting and search

  • Recipient Determination: the method which the Healthcare Action Engine uses to determine who it will send the notification to. This version of the Healthcare Action Engine only supports determining the recipients of a notification based on group assignments.

  • Template: the template that the Healthcare Action Engine uses to transform the content of the card into a format appropriate to the contact system. This version of the Healthcare Action Engine makes one email template available.

  • Status: the status of the notification policy. Notification policies can have one of the following statuses:

    • Active: the Healthcare Action Engine sends the notification to the designated recipients when the conditions specified by the notification policy are met

    • Inactive: the notification policy is inactive; the Healthcare Action Engine takes no action when its conditions are met

    • Silent: the Healthcare Action Engine does not send the notification to the designated recipients when the conditions specified by the notification policy are met. However, the event is logged for testing purposes

You can View An eye icon, Edit A pencil icon, or Delete An icon of a trash bin an existing notification policy by selecting the appropriate icon in the Actions column for that policy.

Selecting the entry for a notification policy in the Notification Policies table expands the table to reveal additional, subordinate rows. These subordinate rows enumerate all the conditions which result in HAE sending a notification according to the selected notification policy. Because notifications can only occur when a certain rule returns a certain card, each of these subordinate rows represents a unique combination of one Rule and one Card which that rule returns. For convenience, each row also provides the Rule Description and the Card Description.

To build a new notification policy, select the New Notification Policy button and follow the steps provided in the section which follows.

Build a Notification Policy

When you select the New Notification Policy button or select the Edit A pencil icon icon for an existing notification policy in the Notification Policies table, the Notification Policy Builder appears.

The Notification Policy Builder contains two components: a selection table pane and a form.

Create a new notification policy by making selections from the selection table pane, advancing through each step of the process: Rules and Cards, Recipients, and Message Template. Then, review your selections and provide more information about your notification policy using the form.

Once you have configured the notification policy, select the Save Notification Policy button to save it and return to the Notification Policies table. Selecting the Cancel button discards the current configuration.

Notification Policy Builder Selection Table Pane

The Notification Policy Builder allows you to configure a notification policy step by step, by selecting components from a series of selection tables: a Rules and Cards table, a Recipients table, and a Message Template table. Make selections at each step, then select Next to advance to the next:

  1. In the Rules and Cards selection table, select the checkboxes which correspond to the rule evaluation outcomes for which the Healthcare Action Engine should send the notification. In other words, when you select the checkbox for a card returned by a rule, the Healthcare Action Engine sends a notification when that rule returns that card. A notification policy can apply to only one rule, but it can apply to multiple evaluation outcomes (cards) for that rule.

  2. In the Recipients selection table, select the method by which the Healthcare Action Engine determines the recipients for the notification. This version of the Healthcare Action Engine only supports determining notification recipients based on groups.

  3. In the Message Template selection table, select the message template which the Healthcare Action Engine uses to construct the notification. This table displays only the message templates associated with the same trigger as the rule you selected in the Rules and Cards table.

Notification Policy Builder Form

In addition to the selection tables, the Notification Policy Builder includes a form which has the following sections:

  • Name: a descriptive label for the notification policy

  • Summary: a short description for the notification policy

  • Rules/Cards: a set of tiles which display the rule evaluation outcomes (rule/card combinations) which result in a notification, according to the notification policy’s current configuration. You can remove a rule/card combination from the notification policy by selecting the delete An icon of a trash bin icon for that rule/card combination’s tile. You can add a rule/card combination by selecting the corresponding checkbox from the Rules and Cards selection table.

  • Recipients: the recipient determination method for the notification policy. This version of the Healthcare Action Engine only supports determining the recipients of a notification based on group assignments. You can specify if a group should be included in the notification policy by selecting the corresponding checkbox from the Recipients selection table.

  • Message Template: the template that the Healthcare Action Engine uses to transform the content of the card into a format appropriate to the contact system. This version of the Healthcare Action Engine makes one email template available.

  • Status: the status of the notification policy (Active or Inactive).

  • Topic: an optional, user-friendly label for the notification policy. Using topics, you can categorize your notification policies for easier sorting and search

FeedbackOpens in a new tab