HealthShare Personal Community Messaging: Sending Messages and Notifications from the Unified Care Record Setup Guide
1. Introduction
IMPORTANT
This article is intended primarily for those who configure the HealthShare Personal Community Workbench and HealthShare Unified Care Record (referred to hereafter as “Unified Care Record”). However, to ensure the success of the configuration effort, the entire project team should review the note regarding business decisions below.
You can set up a Unified Care Record instance and Personal Community to communicate with active Personal Community members (patients and proxies) when certain events occur in the Unified Care Record. The configuration makes use of the clinical data-based subscription capabilities of Unified Care Record as well as the Personal Community secure messaging and event notifications features.
For example, if new health record data arrives for a patient in your Unified Care Record, you might want to notify the patient and their proxy (if any) that new data is available in their record. You can configure the subscription in the Unified Care Record so that only certain types of new data, such as lab results, trigger the notification.
Alerts may be sent in the form of:
-
Messages that arrive in a member's Personal Community inbox, referred to below as “secure messages”
-
Notifications sent to a member’s external email address, mobile phone number, or both, referred to below as “notifications”
Your project team has complete control of the content of secure messages and notifications.
You can also enable member replies to secure messages.
IMPORTANT
Your project team should make the following business decisions regarding alerting Personal Community members of events in your Unified Care Record:
-
Which types of events should trigger notifications. A likely example is the arrival of new health care data in the Unified Care Record
-
Which types of alerts should be sent: secure messages, notifications, or both
-
Whether secure messages should be sent to patients or proxies
-
Whether notifications should be sent to patients, proxies, or both
-
Whether to use an HTTPS connection in development or test environments for alerts
-
How to identify the sender of secure messages
-
The content and style of secure messages and notifications
-
Whether secure messages and notifications should be provided in the language for a locale other than the default US English shipped with Personal Community
This article provides instructions with specific examples on how to enable these alerts. You will most likely need to work with the manager of your product team, the Unified Care Record administrator, and the Personal Community user interface (UI) developer to complete these steps.
To succeed, you do not have to know all of the many details of Unified Care Record subscriptions or Personal Community secure messages and event notifications, but it may help you to read the relevant sections of the documentation before you begin taking the steps below.
See the Unified Care Record Clinical Message Delivery Guide , the HealthShare Personal Community External Messaging Setup Guide , and the event notifications guide.
2. Configuring Personal Community to Receive Messages and Notifications from the Unified Care Record
2.1. Register an Assigning Authority to Represent the Unified Care Record
In most cases, the assigning authorities registered in the Unified Care Record are specific to a clinical group or a provider. They are automatically synced into Personal Community.
Alert configuration requires that you create an assigning authority in your Registry namespace that specifically represents the Unified Care Record.
To add an assigning authority representing the Unified Care Record:
-
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. In this example, an assigning authority with the name
Unified Care Record Alerts
and the codeUCR
is being created. -
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 message 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.
You must assign one of the following roles:
-
HSPortal_Role_API_Messaging — this role provides the minimum permissions necessary to send messages from the external system.
-
HSPortal_Role_API — if you ever plan to use the Clinical Group or Provider API to add or update clinical groups from this external system, assign this role instead.
The username and password can be provided within the SOAP header.
The following XML snippet shows the use of a username and password in the header for authentication and authorization.
2.3. Add a System-Wide Identifiers in the Workbench
For messages and notifications to be sent to Personal Community, system identifiers for the Organization, Clinical Group, and Patient Identifier Types should configured.
-
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 the identifier you are using for patients (Note, this is most likely the Medical Record Number).
-
Under Clinical Group Identifier Types , add Corporate ID-XX .
-
Select Apply to save the changes.
2.4. Register the Unified Care Record as an External System in the Workbench
For the Unified Care Record to route messages and notifications through Personal Community to members, it must be registered as an external system in the Workbench.
To register the Unified Care Record as an external system in the Workbench:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, choose External Systems . This displays the External Systems page.
-
On the External Systems page, choose Add External System . This displays the External Systems Details page.
-
Fill in the fields on this page as follows:
-
Name — Required. The name by which the Unified Care Record will be known as an external system in the Workbench. Use alphabetic characters and hyphens only; no spaces or numbers. In the example below, the name of the external system registration for the Unified Care Record is UCR-EXT.
-
Description — Optional.
-
Enabled — Required. Enables the Unified Care Record to send secure messages and notifications.
-
Allow patient MPI search — Make sure this is selected, because the Unified Care Record includes MPIID only (no other patient identifiers) in the body of each message it sends to Personal Community.
-
Allow message attachments — Leave this option set to No .
-
Allow form requests — Leave this option set to No .
-
Message Types — Select the options as follows:
-
General — If your team wants to send secure messages, select this option.
-
Medical — If your team wants to send secure messages, select this option.
-
Reply — If your team wants to enable member replies to secure messages, select this option.
-
Direct Communication — If your team wants to send notifications, select this option.
-
-
Authorization Settings — Required. Saving the external system registration for the first time automatically generates a random alphanumeric string for API Key . This value will be stored later as part of a new set of credentials in the Unified Care Record.
IMPORTANT
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. You will need to share the new value with the Unified Care Record administrator
-
Patient Identifier Types — Used for Direct Communication. 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.
-
-
Provider Identifier Types — Not applicable for Unified Care Record alerts.
-
Clinical Group Identifier Types — Add a single entry for the assigning authority that you created in the Unified Care Record. In this example, an identifier type of Corporate ID-XX has been added for the Unified Care Record Alerts–UCR assigning authority. (Note that another identifier type is configured for this external system; this is permissible.) You may have to log out and back in to be able to select Corporate ID–XX as an identifier type.
-
Organization Identifier Types — Not applicable for Unified Care Record alerts.
-
- Choose Save to save the data for the external system.
2.5. Create an Organization and Clinical Group to Represent the Unified Care Record in the Workbench
You must create an organization and clinical group to represent the Unified Care Record:
-
Log into the Workbench as a user with the Provider Manager role.
-
Go to the Setup tab.
-
In the activity pane, choose Organizations . This displays the Organizations page.
-
On the Organizations page, choose the Add Organization button. This displays the Organization Details page.
-
Complete the fields as follows:
-
Organization name — Enter a name for the organization. In this example,
Unified Care Record Alerts
is used.IMPORTANT
Since you will be creating a clinical group at the same time you create the organization, this value will appear to Personal Community members as the sending clinical group.
-
Organization ID — Leave this field empty.
-
Assigning Authorities — Leave this field empty.
-
Assigning Authorities from Clinical Groups — Not editable.
-
Building — Leave this field empty.
-
Address line 1 — Required. Any string value is acceptable.
-
Address line 2 — Leave this field empty.
-
City — Required. Any string value is acceptable.
-
State — Leave this field empty.
-
Zip — Leave this field empty.
-
Create a clinical group ? – Make sure to select this field.
-
-
Choose Save to save the data for the organization and the clinical group.
2.6. Set Up the Clinical Group for the Unified Care Record in the Workbench
Now that you have a new clinical group to represent the Unified Care Record as a sender, there are a few more configuration steps to complete.
To finish setting up your new clinical group:
-
Log into the Workbench as a user with the
Provider Manager
role. -
Go to the Setup tab.
-
In the activity pane, choose Clinical Groups . This displays the Clinical Groups page with a list of active clinical groups.
-
On the Clinical Groups page, select the row for Unified Care Record Alerts . This displays the Clinical Group Details page.
-
Change the values of the fields as follows
-
Assigning Authorities — Leave this field empty.
-
Messaging Enabled — If Unified Care Record will send secure messages to members, make sure this field is selected. If only notifications will be sent, you can leave the field unselected.
-
Identifiers — Add an identifier as follows. You will use the clinical group identifier type you created when registering your external system; if you just completed that step, you may have to log out and back in to see it. Note that you can use any value for the ID; here, UCR-SUB was used.
Message flows associated with this clinical group — If your Unified Care Record will send secure messages to which members can reply, you must specify a message workflow. As with all member replies to messages, you can use the Workbench to handle replies from members, or you can configure an external system to process replies. For more information on reply processing, see the Workbench Management Setup Guide .
InterSystems strongly recommends that you select either the “general” or “medical” delivery interface.
-
-
When you are finished entering values, choose Save to save the data for the clinical group.
2.7. Create and Register a Message Template for a Secure Message
IMPORTANT
If you want to alert members to the Unified Record Events only through notifications, you can skip this section.
If your team wants to send secure messages to members, you should create and register at least one secure message template specifically for use by the Unified Care Record. You may need to create and register different templates depending on how many events will trigger alerts.
In the example below, the team wants to send a secure message whenever new health record data of any kind arrives in the Unified Care Record. This requires the creation and registration of a single message template.
2.7.1. Create a Template File for the Secure Message
You must create a new template file for event-based Unified Care Record secure messages.
To create and deploy message templates:
-
Navigate to
<hspc-home> /custom/content/en/
-
Create a new HTML file. The first portion of its filename should indicate the topic of the message, and the last portion of the filename (before the *.html extension) should be –html .
For example, if you wanted to create a message template for use when new health records are received for a member in the Unified Care Record, your file could be named
new-health-records-html.html
The base name of this file, new-health-records , is known as the content key .
-
Add content to the file as appropriate, including any desired HTML markup, and save it.
-
If <hspc-home> /custom/config/email-settings/en/email_subjects.json does not yet exist, copy <hspc-home> /base/config/email-settings/en/email_subjects.json to the custom folder.
-
Add a key-value pair to <hspc-home> /custom/config/email-settings/en/email_subjects.json . If you append a line to this file, make sure the previous line ends with a comma.
The new key-value pair must consist of:
-
A subject key that clearly identifies the purpose of the message template
-
A string for the actual subject of the message
If, for example, your project team wants a subject line of “New Health Records” for messages that use this template. In that case, you would add the following line to email_subjects.json , ensuring that the previous key-value pair is followed by a comma:
“NewHealthRecords” : “New Health Records”
-
- Refresh content.
-
Share the subject key (for example, NewHealthRecords ) and the content key (for example, new-health-records ) with the Workbench administrator. These two values become part of the message template registration within the Workbench.
After completing the steps above, note the values of subject key and content key that correspond to the newly created template. You will use these when registering the message template.
2.7.2. Register the Message Template in the Workbench
To register the new message template:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, choose Message Templates . This displays the Message Templates page.
-
On the Message Templates page, choose the Add Message Template button.
-
Complete the fields as follows:
-
Name — Required. The name of the message template in the Workbench. Based on the creation of a message template for new health records as described above, the name is NHR (short for “New Health Records”).
-
Template key — Required: you can use any alphanumeric string that will aid in the identification of this template. You can reuse the value that you used for the name; in this example, the template key is NHR .
-
Subject key — Required. In practice, the UI developer will give you this value after they create the template. In this example, the subject key is NewHealthRecords .
-
Content key — Required. In practice, the UI developer will give you this value after they create the template. In this example, the subject key is new-health-records .
-
Deliver message to patient’s or proxy’s inbox — If Patient is selected, all messages sent using the template key from this registration will be directed to the patient’s inbox. If Proxy is selected, all messages sent using the template key from this registration will be directed to the inbox of the proxy or proxies for the patient, if any.
-
-
Choose Save to save the data for the message template.
2.8. Create or Customize Content for Unified Care Record Notifications
IMPORTANT
If you want to alert members to Unified Care Record events only through secure messages, you can skip this section.
Like secure messages, notifications rely on content files that the UI developer creates. (Unlike secure messages, however, the setting that dictates whether notifications are sent to patients or proxies (or both) is in the Unified Care Record: see the step regarding adding and configuring the delivery operation.
Personal Community includes a set of six content files that can be used to notify patients, proxies, or both of new health data of any kind in a patient’s record. (The entire set of six files is identified by a single content key that is used within the Unified Care Record, and that key is newdata .) If you want to use this set, the content of the files can be customized by your UI developer.
If the event that will trigger the notifications is sufficiently different from “new health record data” (if, for example, you wanted to use different templates for new lab data and new radiology data), your UI developer will most likely have to create new files. They would assign separate content keys to each set of files: apt key names would be newlabdata and newraddata .
See the section below for instructions on how to customize existing content files or create new ones. For purposes of this example, any new health record data that arrives on the Edge Gateway for a given patient will use one set of files, identified by the content key newdata .
2.8.1. External System Event Notifications
Notifications can be routed through Personal Community to members’ external email addresses or mobile phones when certain events occur within external systems. The files that supply content for these notifications are distinct from those for internal event 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- format .html
and
direct-communication-proxy-newdata- format .html
where format is html (HTML email), text (text email), and sms (text for mobile phones). There are six files total.
You can customize the text of any of these files, and you can apply styles as you would to notifications for internal events.
If your project team wants to use this set of notifications, let the application developer who is creating the framework for external system event notifications know that the content key for these notifications is newdata .
If your project team needs to send other types of external notifications, you can add them as follows:
-
Decide on a content key (similar to newdata ) for the subject of the notification. The key should be all lowercase letters: no numbers or punctuation.
For example, if a new provider is added to a facility where you are a patient, the facility may want to notify all patients of record. An apt content key for your notification files would be newprovider .
-
Create six files: three for patient notifications and three for proxy notifications, in each of the three formats described above. If your content key value is newprovider , your file names would be:
-
direct-communication-patient-newprovider-html.html
-
direct-communication-patient-newprovider-sms.html
-
direct-communication-patient-newprovider-text.html
-
direct-communication-proxy-newprovider-html.html
-
direct-communication-proxy-newprovider-sms.html
-
direct-communication-proxy-newprovider-text.html
-
-
Customize the text and HTML format of these files as needed.
-
If you have not yet copied email-settings.json to <hspc-home> /custom/config/email-settings/en/ , do so.
-
Open email-settings.json and scroll to the end. You will see the following two lines: the first portion of each line identifies the files to which the subject pertains and the portion following the colon will be the subject of the message.
"direct-communication-patient-newdata" : "Important: New $$$APPLICATION messages", "direct-communication-proxy-newdata" : "Important: New $$$APPLICATION messages"
-
Add two new lines to email-settings.json for your custom content key. Make sure to append a comma to the line immediately preceding your two new lines. The very last line of the file should terminate with a double quote, not with a comma.
If your content key value is newprovider , the last four lines of email-settings.json would look like this after your changes:
"direct-communication-patient-newdata" : "Important: New $$$APPLICATION messages", "direct-communication-proxy-newdata" : "Important: New $$$APPLICATION messages", "direct-communication-patient-newprovider" : "Welcome our newest physician to Commonwealth Hospital Network!", "direct-communication-proxy-newprovider" : "Welcome our newest physician to Commonwealth Hospital Network!"
-
Refresh content.
2.9. Localize Secure Messages and Notifications
Your project team may want to allow members to receive secure messages and notifications in the language of their choice. For this to happen, Personal Community must be localized, which includes steps taken by the UI developer and by the Workbench administrator. See the Localization Setup Guide .
2.10. Give Required Information to the Unified Care Record Administrator
The Unified Care Record administrator will need the following information:
-
From the Clinical Group Details page: the type, name, and external system ID of the identifier. The portions of the Type and Name field values that are used in the Unified Care Record are those that follow the hyphen in each field. So, in this case, you would give them the values XX for type, UCR for name, and UCR-SUB for identifier.
-
From the External System Details page: the Name and API key field values. In this example, you would give them the value UCR-EXT for the name and the current API key field value.
-
Whether you are configuring secure messaging, notifications, or both.
-
If you are configuring secure messaging: the Template key value from Message Template Details . In this case, you would give them the value NHR .
-
If you are configuring notifications:
-
the content key from the UI developer (in this case, newdata )
-
whether patients, proxies, or both should receive notifications
-
-
If you will allow member replies to Unified Care Record secure messages: the type of delivery interface you selected when you enabled a message flow (general or medical).
3. Setting Up the Unified Record to Send Messages and Notifications to Personal Community Members
3.1. Create a Set of Credentials for the Personal Community External System
In the Access Gateway production of the Unified Care Record, create a set of credentials for the Personal Community system:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Access Gateway that will be used to send alerts to Personal Community. Use credentials for a user with access to the Interoperability > Credentials page (such as a user with the %HS_Administrator and %EnsRole_Administrator roles).
-
Switch to the namespace for the Access Gateway.
-
Navigate to Interoperability > Credentials .
-
On the right side of the screen, create a new set of credentials as follows:
-
ID — A name of your choice that will distinguish these credentials as belonging to Personal Community
-
User name — the value of the External System Details > Name field in Personal Community (in this case, UCR-EXT )
-
Password — the value of the External System Details > API Key field in Personal Community
-
-
Select Save to save the new set of credentials.
3.2. Create and Test an SSL/TLS Configuration for Personal Community Secure Messaging
To create an SSL/TLS configuration for the Personal Community Secure Messaging API:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Access Gateway that will be used to send alerts to Personal Community. Use credentials for a user with access to the SSL/TLS Configurations page (such as a user with the %HS_Administrator and %EnsRole_Administrator roles).
-
Switch to your Access namespace.
-
Navigate to System Administration > Security > SSL/TLS Configurations .
-
Select Create New Configuration .
-
Enter a name of your choice for the new configuration and leave all the other default values as they are. Make a note of the name, because you will need it to complete the steps below.
-
Select Save to save the new configuration.
-
To test the new configuration, select Test . When prompted. enter the hostname and port of the web server for Personal Community as they are specified in the certificate configured on the Personal Community web server.
3.3. Create a Service Registry Entry for Personal Community Secure Messaging
As with any web service used by the Unified Care Record, a service registry entry must be created for secure messaging:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Registry as a user with access to the Service Registry page (such as a user with the %HS_Administrator role).
-
Navigate to HealthShare > HSRegistry (or your Registry namespace) > Registry Management > Service Registry .
-
For Service Type , choose
SOAP
. -
Select Add Service and complete the fields as follows:
-
Name — A name of your choice. Make a note of it because you will need it for the steps that follow.
-
Host — the hostname of the machine on which your Personal Community instance runs
-
Port — the Personal Community web server port
-
SSL Configuration — the name of the SSL/TLS configuration, if any, that you created previously.
Note
You will need to enter the name manually; it will not be in the drop-down list.
-
URL — the URL of the Secure Messaging API web service: /csp/healthshare/< HSPCnamespace> /services/HSPortal.Production.Service.APIMessageService.cls where < HSPCnamespace> is the namespace chosen when Personal Community was first installed.
-
Username Token Profile — HS_Services
-
Send SAML Assertion — No
-
Check Server Identity — Select this field.
-
-
Select Save to save the service registry entry.
3.4. Add and Configure the Personal Community Delivery Operation
The Personal Community delivery operation, which is part of the Access Gateway production, routes the information needed for secure messages and notifications to Personal Community.
To add and configure the Personal Community delivery operation:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Access Gateway that will be used to send alerts to Personal Community. Use credentials for a user with access to the Access Gateway production (such as a user with the %HS_Administrator and %EnsRole_Administrator roles).
-
Switch to the namespace for the Access Gateway.
-
Navigate to Interoperability > Configure > Production .
-
Next to Operations , select the + icon to add an operation.
-
In the Operation Class drop-down list, select HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation , then select OK .
-
In the list of operations, select HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation .
-
For Settings , enter the following values:
-
Basic Settings :
-
Enabled — Make sure the operation is disabled for now. You will enable it as the last step of secure messaging setup within the Unified Care Record.
-
ServiceName — the name of the service registry entry you created previously.
-
APIKeyCredentials — the name of the credentials set you created previously.
-
Leave all other field values as is.
-
-
Connection Settings :
-
SSL Configuration — Leave this field empty.
-
SSL Check Server Identity — Make sure this field is enabled.
-
Leave all other field values as is.
-
-
Direct Settings :
-
DirectCommunicationRecipients — For notifications only: if you want only patients to receive them, choose Patient . If you want only proxies to receive them, choose Proxy . If you want both patient and proxy to receive them, choose Patient and Proxy .
-
-
SecureMessage Settings (complete these fields if you want to send secure messages):
-
SecureMessageClinicalGroupAAType — Enter the value from the Clinical Group Details — Identifier Type field given to you by the Workbench administrator; in this example, XX .
-
SecureMessageClinicalGroupAACode — Enter the value from the Clinical Group Details — Identifier Name field given to you by the Workbench administrator; in this example, UCR .
-
SecureMessageClinicalGroupIdentifier — Enter the value from the Clinical Group Details — External System ID field given to you by the Workbench administrator; in this example, UCR-SUB .
-
PermitSecureMessageReplies — If your team wants members to be able to reply to secure messages, make sure this field is enabled.
Note
A separate delivery operation to handle incoming Personal Community replies is necessary.
-
-
-
Select Apply to save the changes.
3.5. Define a Delivery Option for Personal Community Alerts
The next sections involve preparation for and setup of subscriptions for secure messages and notifications.
To define a delivery option:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Registry as a user with access to the Delivery Options page (such as a user with the %HS_Administrator role).
-
Navigate to HealthShare > HSRegistry (or your Registry namespace) > Delivery Management > Delivery Options .
-
Select Add Delivery Option and complete the fields as follows:
-
Name — A name of your choice. Note the name, because you will need it for the steps below.
-
DeliveryType — EDI
-
DeliveryOperation — HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation
-
-
Select Save Delivery Option .
3.6. Define Personal Community as a Receiving System
IMPORTANT
This section assumes that you already set up at least one data transformation; to do so, see the "Data Transformations: Creating Custom Clinical Documents" chapter of the Unified Care Record Clinical Message Delivery Guide . That chapter describes several sample transformations that you can use to complete this section: HS.Reports.PatientSummary is recommended. The InstallDemo() and InstallBusDemo() utilities also create sample transformations for use on development and test systems.
To define Personal Community as a receiving system:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Registry as a user with access to the Receiving Systems page (such as a user with the %HS_Administrator role).
-
Navigate to HealthShare > HSRegistry (or your Registry namespace) > Delivery Management > Receiving Systems .
-
Select Add System and complete the fields as follows:
-
System tab:
-
Name — A name of your choice
-
Active — Make sure this field is selected.
-
Leave all other field values as is.
-
Select Save System .
-
-
Delivery Policies tab: select Add Policy and complete the fields as follows:
-
Name — A name of your choice
-
Primary — Make sure this field is selected.
-
Delivery Option — The delivery option you defined in “ Define a Delivery Option for Personal Community .”
-
Transformation — An existing data transformation
-
Access Gateway — The name of the Access Gateway in the Unified Care Record where you configured the delivery operation
-
Endpoint — Leave this field empty.
-
Select Save Policy .
-
-
3.7. Define Subscription Policies for Personal Community Alerts
Secure messaging and notifications both rely on subscription policy setup: each requires its own policy.
This section assumes that you have set up at least one delivery filter: the topic filter Info Type . If you have not yet set up any delivery filters, you can set them up yourself; see the “ Subscription Filters ” chapter of the Unified Care Record Clinical Message Delivery Guide .
The example below shows you how to set up subscription policies for secure messages and notifications. The subscription policy for secure messages illustrated below uses an Info Type topic filter that will trigger on new lab data, while the policy for notifications triggers on new diagnosis data:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Registry as a user with access to the Clinical Data Receipt Subscriptions page (such as a user with the %HS_Administrator role).
-
Navigate to HealthShare > HSRegistry (or your Registry namespace) > Delivery Management > Subscription Management > Clinical Data Receipt Subscriptions .
-
Under Select Recipient > Receiving System , select the receiving system you created previously, In this case, you would select PersonalCommunitySystem .
-
If you are configuring secure messaging: select Add Policy and complete the fields as follows for this example:
-
Policy tab:
-
Name — A name of your choice. In this example, the name is PCSM1 .
-
Subscription Basis — All
-
Delivery Policy — The policy you created previously: in this example, PCNotification .
-
Transformation — Leave this field empty.
-
Subject — Enter PersonalCommunity:Secure:medical: templateKey , where templateKey is the value of the template key field in the message template registration in the Workbench. This value should be available from the Workbench administrator. In this example, the value entered is PersonalCommunity:Secure:medical:NHR .
-
Effective Date — Make sure this field value is the current date, or the date you wish alerts to begin.
-
Expiration Date — If secure messaging should end on a particular date, enter it here; otherwise, leave this field empty.
-
Apply Consent — Make sure this field is enabled.
-
Select Save Policy .
-
-
Topic Filters tab: select Add Topic Filter and complete the fields as follows:
-
Topic — Info Type
-
Operator — Equals
-
Parameters — Enter LAB . This will cause the policy to trigger on new lab data.
-
Select Save Topic Filter . This topic filter will cause the subscription to be triggered if new health record data of type LAB arrives on the Edge Gateway.
-
-
-
If you are configuring notifications: select Add Policy and complete the fields as follows for this example:
-
Policy tab:
-
Name — A name of your choice. In this example, the name is PCDC1 .
-
Subscription Basis — All
-
Delivery Policy — The policy you created previously: in this example, PCNotification .
-
Transformation — Leave this field empty.
-
Subject — Enter PersonalCommunity:Direct: contentKey , where contentKey was assigned by the UI developer if new content files were created. Here, the value used is the content key for the notification files shipped with Personal Community, and so the value you would enter is PersonalCommunity:Direct:newdata .
-
Effective Date — Make sure this field value is the current date, or the date you wish alerts to begin.
-
Expiration Date — If notifications should end on a particular date, enter it here; otherwise, leave this field empty.
-
Apply Consent — Make sure this field is enabled.
-
Select Save Policy .
-
-
Topic Filters tab: select Add Topic Filter and complete the fields as follows:
-
Topic — Info Type
-
Operator — Equals
-
Parameters — Enter DXG . This will cause the policy to trigger on new diagnostic data.
-
Select Save Topic Filter .
-
-
3.8. Enable the Personal Community Delivery Operation
To enable the Personal Community delivery operation:
-
Log in to the Management Portal on the Unified Care Record instance that hosts the Access Gateway where you set up the delivery operation. Use credentials for a user with access to the Access Gateway production (such as a user with the %HS_Administrator and %EnsRole_Administrator roles).
-
Switch to the namespace for the Access Gateway.
-
Navigate to Interoperability > Configure > Production .
-
Select HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation .
-
Under Settings > Basic Settings , select Enabled .
-
Select Apply to save the changes.
3.9. Test the Subscription Setup
To test the subscription setup on a development or test instance of Personal Community:
-
Make sure that you have a file that includes HL7 lab and diagnostic data for an active member of Personal Community.
-
Log into the Workbench for your test instance of Personal Community.
-
In the Members > Member Details page for the member for whom you have HL7 data:
-
Select Edit .
-
Enter an external email address at which you can receive email.
-
Select Update .
-
-
On the machine that hosts the Edge Gateway for your Unified Care Record, drop the HL7 data file into the
Data/EdgeGateway/HL7In
directory. If you enabled notifications, you should receive an email notification at your external email address that new data is present. If you enabled secure messaging, you should receive new email within Personal Community.