Skip to main content

HealthShare Personal Community Messaging: System Inititated Notifications from External Systems Setup Guide




1. Overview

An integral part of an organization's patient engagement strategy is the ability to notify patients of information about their medical care, such as when new data is available.  Organizations may use the notification capabilities of Personal Community to send notifications from trusted external systems.  Unlike Secure Messaging, notifications are sent directly to a patient or proxy's email or phone.  Notifications should not be used if patient health information needs to be sent in the communication.

Personal Community supports this functionality with a SOAP API and a REST API.  All new integrations should use the REST API as this will be enhanced in the future.

2. Configuring Personal Community to Recieve Notifications from External Systems

Personal Community will need to be configured for notifications when using either the Notification REST API or the DirectCommunication webmethod of the  Secure Messaging SOAP API. 

2.1. Register an Assigning Authority in the Unified Care Record to Represent the External System

In most cases, the assigning authorities registered in the Unified Care Record are specific to a clinical group or a provider. These values are automatically synced into Personal Community.

Sending messages from an external system requires that you create an assigning authority in your Registry namespace that specifically represents the system.

To add an assigning authority:

  1. Log in to the Management Portal for your Unified Care Record as a user with access to the  Assigning Authority Registry  page (such as a user with the   %HS_Administrator  role).

  2. Navigate to  HealthShare  >  HSRegistry  (or your registry namespace) >  Registry Management  >  Assigning Authority Registry .

  3. In  Select an Identifier Type , choose  Corporate ID .

  4. Add a new assigning authority, including  Name   and   Code entries. 

  5. Select  Save Assigning Authority .

  6. If you will be moving on to the Workbench configuration steps described below, wait a few minutes for the new assigning authority to be synced to Personal Community.

2.2. Configure your IRIS User in Personal Community

When a notification arrives from an external system, it must contain the username and password of an IRIS user account that has the appropriate role. InterSystems IRIS for Health™ authenticates the user’s credentials and ensures that the user account is authorized to handle the message.

That user account must be created on your Personal Community instance. See “ Create a New User Account ” and “ Modify a User's Roles ” for information on how to create an IRIS user account and assign roles to it.

For either the Notification REST API, or the Direct Communication SOAP API you must assign the following role:

  • HSPortal_Role_API_Messaging

2.3. Add System Wide Identifiers in the Workbench

When a notification is sent to a Personal Community member from an external system, Personal Community recognizes the member by means of   entity identifiers   in the message’s metadata.

An   identifier   type   is a general category of identifier,   such as medical record number . The identifier is the ID in the external system for a patient.

Identifier Type Identifier Examples
Medical Record Number “4501”, “RN000000020”

To specify the acceptable identifier types for the use of any external system with your Personal Community instance:

  1. Log in to the Workbench as a user who has the   Configuration Manager   role.

  2. Go to the   Setup   tab.

  3. On the   Setup   tab, choose   Site Configuration . This displays the   Site Configuration Settings   page.

  4. Under   Patient Identifier Types , add one or more identifier types that Personal Community will accept from any external system for patients.

  5. Select   Apply   to save the changes.

2.4. Register the External System in the Workbench

Each external system that will update clinical group and provider data in Personal Community must be registered in the Workbench.

If the external system already is registered in the Workbench for other APIs, you do not need to add another registration. However, be sure not to modify any existing settings unintentionally.

To register an external system:

  1. Log in to the Workbench as a user who has the   Configuration Manager   role.

  2. Go to the   Setup   tab.

  3. On the   Setup   tab, select   External Systems

  4. On the   External Systems   page, select   Add External System .

  5. Fill in the fields on this page as follows:

    • Name   — Required. The name by which the external system will be known in the Workbench. This name will also be used in messages to and from the external system.

    • Description   — Optional. A description of the external system.

    • Enabled   — Required: Enables the external system to send notifications.

    • Allow patient MPI search   If selected, allows the patient to be looked up by MPIID. This eliminates the need to provide both assigning authority information and medical record number in a message.

    • Allow message attachments   — Not applicable for event notifications .

    • Allow form requests   — Not applicable for  event notifications .

    • Message Types   To enable a message type for this external system, select it in the list. To prohibit messages of a type from being sent, deselect that type. The available types are:

      • General –  Not applicable for event notifications .
      • Medical – Not applicable for  event notifications .
      • Reply – Not applicable for  event notifications .
      • Direct Communication – Make sure this checkbox is selected.
    • Authorization Settings   — Required. Saving the external system for the first time automatically generates a random alphanumeric string for   API Key . Make sure to share this value with the application developer who creates the external system’s notification framework.

      IMPORTANT

      The API key is required for any use of the Clinical Group and Provider API, and, unlike IRIS user credentials, will not be deactivated if someone leaves your organization. If there is reason to believe that the API key might be used in an unauthorized fashion, you can generate a new API key with the   Generate API Key   button.


    • Patient Identifier Types   — I f your team is using an identifier other than MPIID to locate patients for notifications, at least one entry is required for each assigning authority whose clinical groups and providers will send messages. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

      • Choose an identifier type from the dropdown, then choose the name for the desired assigning authority.

      • Notification must use this identifier type for patients; other identifier types will cause notifications to be rejected.

  6. When you are finished entering values, choose   Save   to save the data for the external system. 

3. Configuring Content for Notifications

Personal Community ships with a set of files that can be used to notify members of new data in their external system health records. Depending on the needs of the external system, these notifications can be sent to the patients whose data is affected, their proxies, or both. These files are named as follows:
  • direct-communication-patient-newdata- text .html
  • direct-communication-patient-newdata- html .html
  • direct-communication-patient-newdata- sms .html
  • direct-communication-proxy-newdata- text .html
  • direct-communication-proxy-newdata- html .html
  • direct-communication-proxy-newdata- sms .html

To use these files as is, pass  newdata is the value for your content key.

3.1.1. Update Existing New Data Content Files

To customise the default new data content files:

  1. If there is not already a custom copy of these content files, copy the existing files from

    <hspc-home> / base /content/ locale code/

    to

    <hspc-home> / custom /content/ locale code /

    Note

    If such a file already exists, do not create a new copy, as this may overwrite any customizations your organization has already made in it.

  2. If there is not already a custom copy of the email subjects configuration file, copy the existing file from

    <hspc-home> / base /config/email_settings/ locale code/

    to

    <hspc-home> / custom /config/email_settings/ locale code /

  3. Edit the custom copy of the files as required for your organization.
  4. Refresh Content in the Workbench

    To refresh content:

    1. Log into the Workbench as a user who has the Configuration Manager role.

    2. Go to the Content tab.

    3. On the activity pane, select Content Updates . This displays the Content Updates page.

    4. On the Content Updates page, choose Refresh Content .

    This updates every aspect of each application to display the custom content, including text, images, and so on.

    If changes are not visible after you refresh content, you may need to clear your browser cache.

3.1.2. Create Additional Content Files for Workflows

For each workflow that will generate a notification, a dedicated set of content files should be created.  To create new files:

  1. Decide on the  content key for the subject of the notification. This key should be all lowercase letters with no numbers of punctuation.
  2. Create six files for each language that is enabled in Personal Community: three for patient notifications and three for proxy notifications, one for each of the supported formats.  The files should be named as follows:
    1. direct-communication-patient- <custom content key name> -html.html
    2. direct-communication-patient- <custom content key name> -sms.html
    3. direct-communication-patient- <custom content key name> -text.html
    4. direct-communication-proxy- <custom content key name> -html.html
    5. direct-communication-proxy- <custom content key name> -sms.html
    6. direct-communication-proxy- <custom content key name> -text.html
  3. Customize and translate the text and HTML format of these files as need
  4. If there is not already a custom copy of email-settings.json, copy this file from

    <hspc-home> / base /config/email-settings/ locale code/

    to

    <hspc-home> / custom /config/email-settings/ locale code /

  5. Open  email-settings.json for each configured local and scroll to the end.  You will see the following two lines
    1. "direct-communication-patient-newdata" : "Important: New $$$APPLICATION messages"
    2. "direct-communication-proxy-newdata" : "Important: New $$$APPLICATION messages"
  6. Add two new lines to  email-settings for each custom content key.  The first portion of the line identifies the files to which the subject pertains and the second portion is the subject of the message to be used in emails.
  7. Refresh Content in the Workbench

    To refresh content:

    1. Log into the Workbench as a user who has the Configuration Manager role.

    2. Go to the Content tab.

    3. On the activity pane, select Content Updates . This displays the Content Updates page.

    4. On the Content Updates page, choose Refresh Content .

    This updates every aspect of each application to display the custom content, including text, images, and so on.

    If changes are not visible after you refresh content, you may need to clear your browser cache.

4. Sending Notifications from External Systems

4.1. Required Information for Notifications

To create the secure messaging client for an external system, the following information will be required:
  • IRIS user credentials for message transmission

  • System name and API key

  • Patient identifier types and identifiers

  • Content key

The table below will help you locate the information needed.

Application Developer Needs Value For (Notification REST API) Application Developer Needs Value For (Using Secure Messaging SOAP API) Workbench Location Workbench UI Field
Username and password for system authentication Username and password for system authentication N/A N/A
system.name System.Name Setup  >  External Systems  >  External System Details Name
system.apiKey System.APIKey Setup  >  External Systems  >  External System Details API Key
patientList.patientIdentifier.assigningAuthorityType PatientIdentifier.

AssigningAuthorityType

Setup  >  External Systems  >  External System Details The characters   after   the hyphen in the   Patient Identifier Types   field for the clinical group that will be sending the message. For example, the patient identifier type for the clinical group represented by CLCL is   MR , for medical record number.
patientList.patientIdentifier.assigningAuthorityCode PatientIdentifier.

AssigningAuthorityCode

Setup  >  External Systems  >  External System Details The characters   after   the hyphen in the   Patient Identifier Types   —>   Name   field for the clinical group that will be sending the message. For example, the assigning authority code for the clinical group represented by CLCL is   CLCL .
patientList.patientIdentifier.id or patientList.mpiid PatientIdentifier.ID or

Patient.MPIID

Tasks  >  Enroll Patient  >  Patient Details The patient’s MPIID and other identifiers for each assigning authority are displayed on this page.
contentKey ContentKey N/A The value of the   content key   field for the relevant notification.

4.2. Sending Notifications using the REST API

4.2.1. About the Notification REST API

Swagger documentation for the Notification REST API is available   here .

4.3. Sending Notifications using the SOAP API

Usage of the Notification REST API is encouraged over the Secure Messaging SOAP API. Any future enhancements to notification functionality will only be developed against the Notification REST API. The Secure Messaging SOAP API may eventually be deprecated.

The Secure Messaging API is a set of SOAP web services that allows for the sending of secure messages and notifications to Personal Community.  You will use the SendDirectCommunication method to send direct notifications to patients and proxies.

4.3.1. The Secure Messaging API WSDL

The WSDL for the Secure Messaging API can be found at the following URL:

<hostname> : <port-number> / csp / healthshare / <namespace> / HSPortal.Production.Service.APIMessageService.cls?WSDL

Authentication is required; the Workbench administrator can give you a set of credentials to do so. You can consume the WSDL using the IDE of your choice.

4.3.2. Sending a Direct Communication

You will use the SendDirectCommunication method for event notifications.

The  pMessage node of this method includes a  DeliverTo  parameter whose possible values are:

  • Patient – deliver the notification to the patient only. This is the default value.
  • Proxy – deliver the notification to the patient's proxies only.
  • PatientAndProxy – deliver the notification to both the patient and their proxies.

Required fields to send a direct communication are:

  1. System.Name   — the name of the sending external system as it is registered in the Workbench. It can be a random alphanumeric string.

  2. System.APIKey   — the value of the   API Key   field for the sending external system as it is registered in the Workbench.

  3. For the   Patient   node, you can identify the patient either by an identifier specific to a clinical group, such as a medical record number, or by their MPIID.

    • If you want to use an identifier specific to a clinical group:

      • PatientIdentifier.AssigningAuthorityType   — The patient identifier type for the sending clinical group in the Workbench.

      • PatientIdentifier.AssigningAuthorityCode   — The code for the assigning authority represented by the clinical group. In most cases this will be identical to the value of   SendingGroup.AssigningAuthorityCode .

      • PatientIdentifier.ID   — The identifier (such as medical record number) for the patient.

      • Do not include the   Patient.MPIID   node in the request.

    • If you want to use MPIID:

      • Ensure that the external system is configured within the Workbench to allow it: speak with the Workbench administrator.

      • Set   Patient.MPIID   to the value of the MPIID from the patient index. The Workbench administrator can verify the MPIID by navigating to   Tasks   >   Enroll Patient , searching for the patient, and checking the list of   Identifiers on Record .

      • Do not include the   Patient.PatientIdentifier   node in the request.

  4. ContentKey – the identifier for the appropriate content files, stored in your Personal Community instance that will be sent.


You should provide for error handling as well. The relevant fields in an error response are:

  • Status   — In an error condition, the value of this field is   ERROR ; otherwise, the value is   OK .

  • ErrorCode   — The system code for the error.

  • ErrorString   — A description of the error.