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:
-
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). -
Navigate to HealthShare > HSRegistry (or your registry namespace) > Registry Management > Assigning Authority Registry .
-
In Select an Identifier Type , choose Corporate ID .
-
Add a new assigning authority, including Name and Code entries.
-
Select Save Assigning Authority .
-
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:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, choose Site Configuration . This displays the Site Configuration Settings page.
-
Under Patient Identifier Types , add one or more identifier types that Personal Community will accept from any external system for patients.
-
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:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, select External Systems .
-
On the External Systems page, select Add External System .
-
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.
-
-
-
When you are finished entering values, choose Save to save the data for the external system.
3. Configuring Content for Notifications
- 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:
-
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.
-
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 /
- Edit the custom copy of the files as required for your organization.
-
Refresh Content in the Workbench
To refresh content:
-
Log into the Workbench as a user who has the
Configuration Manager
role. -
Go to the Content tab.
-
On the activity pane, select Content Updates . This displays the Content Updates page.
-
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:
- Decide on the content key for the subject of the notification. This key should be all lowercase letters with no numbers of punctuation.
-
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:
- direct-communication-patient- <custom content key name> -html.html
- direct-communication-patient- <custom content key name> -sms.html
- direct-communication-patient- <custom content key name> -text.html
- direct-communication-proxy- <custom content key name> -html.html
- direct-communication-proxy- <custom content key name> -sms.html
- direct-communication-proxy- <custom content key name> -text.html
- Customize and translate the text and HTML format of these files as need
-
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 /
-
Open
email-settings.json
for each configured local and scroll to the end. You will see the following two lines
- "direct-communication-patient-newdata" : "Important: New $$$APPLICATION messages"
- "direct-communication-proxy-newdata" : "Important: New $$$APPLICATION messages"
- 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.
-
Refresh Content in the Workbench
To refresh content:
-
Log into the Workbench as a user who has the
Configuration Manager
role. -
Go to the Content tab.
-
On the activity pane, select Content Updates . This displays the Content Updates page.
-
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
-
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:
-
System.Name — the name of the sending external system as it is registered in the Workbench. It can be a random alphanumeric string.
-
System.APIKey — the value of the API Key field for the sending external system as it is registered in the Workbench.
-
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.
-
-
-
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.