Skip to main content

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:

  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. In this example, an assigning authority with the name  Unified Care Record Alerts  and the code  UCR  is being created.

  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 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.

  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 the identifier you are using for patients (Note, this is most likely the Medical Record Number).
  5. Under   Clinical Group Identifier Types , add   Corporate ID-XX

  6. 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:

  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   External Systems . This displays the   External Systems   page.

  4. On the   External Systems   page, choose   Add External System . This displays the   External Systems Details   page.

  5. 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.

  6.  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:

  1. Log into the Workbench as a user with the   Provider Manager   role.

  2. Go to the   Setup   tab.

  3. In the activity pane, choose   Organizations . This displays the   Organizations   page.

  4. On the   Organizations   page, choose the   Add Organization   button. This displays the   Organization Details   page.

  5. 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.

  6. 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:

  1. Log into the Workbench as a user with the Provider Manager role.

  2. Go to the   Setup   tab.

  3. In the activity pane, choose   Clinical Groups . This displays the   Clinical Groups   page with a list of active clinical groups.

  4. On the   Clinical Groups   page, select the row for   Unified Care Record Alerts . This displays the   Clinical Group Details   page.

  5. 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.

  6. 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:

  1. Navigate to

    <hspc-home> /custom/content/en/

  2. 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 .

  3. Add content to the file as appropriate, including any desired HTML markup, and save it.

  4. 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.

  5. 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”

  6. Refresh content.
  7. 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:

  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   Message Templates . This displays the   Message Templates   page.

  4. On the   Message Templates   page, choose the   Add Message Template   button.

  5. 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.

  6. 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:

  1. 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 .

  2. 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

  3. Customize the text and HTML format of these files as needed.

  4. If you have not yet copied   email-settings.json   to   <hspc-home> /custom/config/email-settings/en/ , do so.

  5. 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"
    
    
  6. 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!"
    
    
    
  7. 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:

  1. 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).

  2. Switch to the namespace for the Access Gateway.

  3. Navigate to   Interoperability   >   Credentials .

  4. 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

  5. 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:

  1. 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).

  2. Switch to your Access namespace.

  3. Navigate to   System Administration   >   Security   >   SSL/TLS Configurations .

  4. Select   Create New Configuration .

  5. 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.

  6. Select   Save   to save the new configuration.

  7. 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:

  1. 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).

  2. Navigate to   HealthShare   >   HSRegistry   (or your Registry namespace) >   Registry Management   >   Service Registry .

  3. For   Service Type , choose SOAP .

  4. 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.

  5. 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:

  1. 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).

  2. Switch to the namespace for the Access Gateway.

  3. Navigate to   Interoperability   >   Configure   >   Production .

  4. Next to   Operations , select the   +   icon to add an operation.

  5. In the   Operation Class   drop-down list, select   HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation , then select   OK .

  6. In the list of operations, select   HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation .

  7. 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.

  8. 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:

  1. 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).

  2. Navigate to   HealthShare   >   HSRegistry   (or your Registry namespace) >   Delivery Management   >   Delivery Options .

  3. 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

  4. 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:

  1. 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).

  2. Navigate to   HealthShare   >   HSRegistry   (or your Registry namespace) >   Delivery Management   >   Receiving Systems .

  3. 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:

  1. 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).

  2. Navigate to   HealthShare   >   HSRegistry   (or your Registry namespace) >   Delivery Management   >   Subscription Management   >   Clinical Data Receipt Subscriptions .

  3. Under   Select Recipient   >   Receiving System , select the receiving system you created previously, In this case, you would select   PersonalCommunitySystem .

  4. 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.

  5. 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:

  1. 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).

  2. Switch to the namespace for the Access Gateway.

  3. Navigate to Interoperability  >   Configure   >   Production .

  4. Select   HS.Gateway.Access.Push.PersonalCommunity.DeliveryOperation .

  5. Under   Settings   >   Basic Settings , select   Enabled .

  6. 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:

  1. Make sure that you have a file that includes HL7 lab and diagnostic data for an active member of Personal Community.

  2. Log into the Workbench for your test instance of Personal Community.

  3. In the   Members   >   Member Details   page for the member for whom you have HL7 data:

    1. Select   Edit .

    2. Enter an external email address at which you can receive email.

    3. Select   Update .

  4. 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.