For each external system, answer the following questions:

1. Regarding messages sent   from   Personal Community   to   the external system:

   1. What APIs (if any) already exist?

   2. Is a new interface needed on the external system to support this?

   3. What message structures does the external system support as part of its existing workflows?

   4. Are those structures extensible?

   5. Are the message contents limited to plain text?

   6. What structures does the system’s message format support?

2. Regarding messages sent   from   the external systems   to   Personal Community:

   1. Can the system make calls to the Personal Community Secure Message API?

   2. What are the Workbench object IDs and assigning authority codes of the clinical group and provider? This information is required for meaningful use reporting within the Workbench.

   3. Is there a need to send messages with pre-written content?

   4. Are there events that should automatically trigger messages?

3. Regarding message flow:

   1. Can providers initiate communication with members?

   2. Can members respond to messages from providers?

4. Regarding recipient identification:

   1. How does the external system identify members (that is, members of Personal Community)?

   2. How does the external system identify its recipients such as providers or other staff?

   3. If the external system requires identifying recipients individually, how do messages differentiate one individual from another? (Personal Community has a group-oriented model, and processes all messages to each provider group uniformly; this requires each message to include content that identifies the particular member of that group, if necessary.)

   4. What is required so that the correct identifiers are available to ensure delivery to the correct recipient? (Note that Personal Community allows for site-specific properties to be defined for message flows, so identifiers may be stored this way.)

5. Regarding message tracking:

   1. Is it possible to allow for responses from members to be tied to the original message? (This generally requires a field to store the original message ID that was sent to the external system.)

6. Regarding varied implementations:

   1. If a particular system is in use for multiple activities, does it have different constraints for each activity?

   2. Does a particular system support different configurations, such as for different provider groups, which may require different behaviors for each group?

When a member sends a message, Personal Community determines how to route the message based on the message type (medical question, billing question, etc.) and the recipient (clinical group). Specifically, the following sequence of events occur:

1. Personal Community creates a message wrapper object that includes the underlying message as well as some information about the intended recipient (the care provider at a particular location).

2. Personal Community looks up the appropriate delivery interface based on the message type and clinical group (which comprise the message flow). This delivery interface allows Personal Community to communicate with the external system.

3. If the delivery interface class is a subclass of   HSPortal.Delivery.ExternalSystem , then Personal Community sends the message wrapper object to the   HSPortal_MessageHandler_ExternalSystem   business process.

4. The   HSPortal_MessageHandler_ExternalSystem   business process then calls the delivery interface’s   SendMessage   method (which is a user-overridden method) to control transmission of the message to the external system.   SendMessage   takes two arguments: the message wrapper object and the business process object.

5. The delivery interface’s   SendMessage   method   should not   contain code that communicates with the external system. Instead, it should send a message to a business operation that is responsible for delivering messages to the external system. The message should be sent using code such as:

   set status = pContext.SendRequestAsync("YourBusinessOperationName", pMessageWrapper)
   

   Note

   The code may also use the   SendRequestSync   method, but this method is not recommended, as it may delay feedback to the member.

6. The business operation that handles communication with the external system then performs most, if not all, of the following steps (also using user-implemented code):

   1. Examines the following pieces of information:

      • Member information associated with the incoming message.

      • Additional information about the member, such as the member’s identifiers for the external system.

      • Additional information about the recipient, which may be stored in the options for the delivery interface or may be tied to the provider involved.

   2. Formats the outgoing message according to the capabilities and requirements of the external system. (This also depends on the specific type of message being handled.)

   3. Sends the message to the external system using a protocol and transmission channel that the external system supports.

The delivery interface gathers any interface-specific configuration information and directs the message to the correct business operation. The delivery interface’s name also appears in the drop-down list when Workbench administrators configure a message flow.

To create a delivery interface for your external interface, and make it available in the Workbench, the steps are:

1. Extend the   HSPortal.Delivery.ExternalSystem   class.

2. Override the following methods in order to implement the required workflow behavior for your site:

   • %GetInterfaceName   – Displays the name of the messaging interface in the Delivery Interface list on the page for creating or modifying the message flow associated with a clinical group. (This is the   Create Flow   or   Modify Flow   page, available through   Setup   >   Clinical Groups   > the group name >   Create Message Flow   or the   Modify   link for an existing message flow for the clinical group.)

   • %MapOptionKeyToInternalValue   – If your interface has selectable options, allows an option key to be mapped to a value internal to Personal Community. See   HSPortal.Delivery.Workflow   for an example implementation.

   • SendMessage   – Uses the information in the message wrapper to assemble a message for the external system; uses either   SendRequestAsync   or   SendRequestSync   to send that message to the business operation that delivers messages to the external system.

     IMPORTANT

     Your subclass(es) of   HSPortal.Delivery.ExternalSystem   need to handle every message type supported by your external system. You must override the   SendMessage   method in each subclass, and must provide all the available information about the sender, recipient, and message to the external system.

3. Override the   Active   parameter and set its value to 1. This parameter controls whether or not the interface is available to be selected in the Workbench.

4. Compile the class.

3.2.1. Additional Configuration of the Delivery Interface

Each delivery interface can specify that some options should be specified on a per-flow basis using the   %GetConfigurationLayout   method, and then using the   %OnCreateRecipientMap   and   %OnUpdateRecipientMap   callbacks. The key feature here is that you can include information that identifies which inbox or pool messages for the flow should be sent to in the external system. In general, this information is specific to each message flow (that is, to each clinical group and message type), so that the information is stored and configured along with each flow. The value that you pass to   %GetConfigurationLayout   should ensure that any values entered by the user are stored under   Options.[SettingName] . For an example, see the   %GetConfigurationData   and   %GetConfigurationLayout   methods in the   HSPortal.Delivery.Workflow   class.

To be able to select a delivery interface when configuring a workflow group, you must first associate the delivery interface with the Personal Community production. To do this:

1. Logon to the Management Portal for the production as a user with the   %EnsRole_Administrator   role or one with greater privileges.

2. Set up the business operation associated with the delivery interface:

   1. In the Personal Community namespace, go to the   Production Configuration   page (from the Management Portal Home page,   Interoperability   >   Configure   >   Production ).

   2. On the   Production Configuration   page, under   Operations , select the   +   icon, to add a new business operation. This displays information the   Business Operation Wizard .

   3. Complete the fields on the wizard, specifying the required information about the code that communicates with the external system.

   4. Select   OK to save the business operation.

3. Set up the business process associated with the delivery interface:

   1. Also on the   Production Configuration   page, under   Processes , select the   +   icon, to add a new business process. This displays information the   Business Process Wizard .

   2. Complete the fields on the wizard, specifying the required information about the delivery interface.

   3. Select  OK to save the business process.

The delivery interface is now available for selection when setting up a message flow for a clinical group.

1. Lo g into the Workbench as a user with the  Configuration Manager  role.

2. Go to the  Configuration Application   page ( Setup  >  Configuration Application ) and select the  Feature Control  tab.  In the activity pane, select   Configure Messaging .  

3. Select  Edit Mode   to make edits to the fields described in the following steps.

4. To the right of the   Messaging box, ensure that the   Enable   checkbox is selected.

5. Once the   Configure Messaging section is expanded, select from the current settings:

1. • Allow patient to send messages -  allows messaging functionality for members. Once selected, you must choose at least one of the following message types:
     • Medical Question - allows members to send a message specifically labeled as a "medical question".
     • General Question - allows members to send a message specifically labeled as a "general question".
     • Billing Question - allows members to send a message specifically labeled as a "billing question".
   • Allow patient to send replies - allows members to reply back to a message sent by a provider.
2. After you have finished, select   Submit   at the bottom of the page to save your changes. 

The Secure Messaging classes handle inbound SOAP messages from external systems as follows:

1. The web server used by Personal Community passes the message to Personal Community. If the Workbench administrator has enabled HTTPS-only communications for SOAP APIs, your request must be made over HTTPS.

2. The IRIS user whose username and password were provided in the SOAP header must be authenticated and their roles within Personal Community checked. See “ Authentication and Authorization ”.

3. The name and API key supplied for the external system are verified against those that were configured in the Workbench.

4. If form requests or message template keys are present in the message, a check is done to make sure they are in fact allowed for the external system.

5. Form keys and message template keys, if present, are validated to ensure they are present in Personal Community.

6. The patient’s MPIID or identifier provided in the message is then looked up first on the Unified Care Record Registry and then within Personal Community:

   • If the message provides the MPIID and it is found on the Registry, a list of patient identifiers associated with that MPIID is returned.

   • The identifiers are checked against Personal Community to ensure the member has an account.

7. After patient lookup succeeds, the identifiers for the sending/reply–to clinical group and sending provider are verified.

8. A response is returned to the client with the appropriate status code (and error code and string if needed). The message processing below occurs asynchronously.

9. Assuming that all of the steps above were successful, Personal Community:

   • Creates an empty message in its native format.

   • Adds the subject line and text from the SOAP message or incorporates text from the message template identified in the message.

   • If replies were indicated as allowed in the body of the SOAP message, assigns the sending clinical group as the reply-to provider and clinical group. If a different reply-to clinical group was is desired, it should be specified in the message.

   • Includes the appropriate attachments, scanning them for viruses first if virus scanning is enabled.

   • Routes the message to the appropriate member.

10. The delivery (or delivery failure) of the message is logged in the production.

11. If the member is allowed to reply, and does so, the reply message is routed back to the external system using the delivery interface configured above.

You can use either the   SendGeneralMessage   or   SendMedicalMessage   operation for your messaging needs.

To send a message with only those fields that are required, include:

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

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

3. SendingGroup.AssigningAuthorityType   — The identifier type configured for the sending clinical group in the Workbench.

4. SendingGroup.AssigningAuthorityCode   — The assigning authority code for the clinical group configured in the Workbench.

5. SendingGroup.ID   — The external system’s identifier for the clinical group. This value is configured for each provider in consultation with someone who knows the data in the external system.

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

7. Text   — The body of the message. You must supply either body text or a message template: see the description of optional fields below.

8. ReplyAllowed   — Whether or not replies from patients are allowed: 1 for yes, 0 for no. If replies are desired, a messaging workflow must be configured for the clinical group.

Optional information for a message includes:

• Subject   — A subject line for the message. This can be supplied here or by a message template: see below.

• ReplyToGroup   — Populate the children of this node if the reply should be directed to a clinical group other than the sending group.

• SendingProvider.AssigningAuthorityType   — This field indicates the identifying code in the Unified Care Record for the   entity identifier type , such as doctor number, that your project team has chosen to accept for providers within a specific clinical group. Confer both with the Workbench administrator as well as the Unified Care Record administrator to get this value.

  Note

  Provider information does not have to be included in a message: you can send a message on behalf of an entire clinical group. However, to be counted for meaningful use purposes, the message must include provider information.

  The Workbench administrator can give you the identifier type configured for providers for your system.

• SendingProvider.AssigningAuthorityCode   — The Unified Care Record code for the provider’s clinical group. The Workbench administrator can give you this value.

• SendingProvider.ID   — The external system’s   entity identifier   for the provider. The Workbench administrator can give you this value.

• Attachments:

  • Enclose the array of attachments for the message in the   Attachments   node.

  • Attachment.Filename   — the filename, with appropriate extension, that will appear for the attachment in the member’s Personal Community inbox.

  • Attachment.ContentType   — the MIME type of the attachment, such as   application/pdf .

    To view a list of supported file types, enter the following command in the Terminal within your Personal Community namespace:

    write $listtostring(##class(HSPortal.Delivery.Workflow).%GetSupportedAttachmentTypes())
    

    To view a list of supported MIME types for the file types you retrieved:

    1. Log into the Management Portal and switch to your Personal Community namespace.

    2. Go to   System Explorer   >   SQL   and select   Go .

    3. In the   Execute Query   field, enter the following SQL query:

       SELECT Code, Type from HSPortal_Delivery_Settings.MimeType
       

       The displayed list shows all valid MIME types for Personal Community message attachments.

  • Attachment.Content   — the attachment itself in MTOM format.

  • Attachment.CharSet   — If the attachment uses a character set different from that used for the SOAP message, specify it here. If this field is empty, the character set specified for the SOAP message will be used for the attachment, and if the SOAP message does not specify a character set, the default is UTF-8.

• Message templates: you can configure your messages to use templates that provide pre-written content. Specify the   MessageTemplateKey   for the desired template, which you can obtain from the Workbench administrator, and omit the   Subject   and   Text   fields.

• TimeCreated   — The timestamp of the message in   yyyy - mm - dd   T   hh : mm : ss [. s ][ TZD ] format. If this field is omitted,   TimeCreated   is set to the current time.

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.

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.

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.

<soapenv:Header>
   <wsse:Security soapenv:mustUnderstand="1" 
       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
           oasis-200401-wss-wssecurity-secext-1.0.xsd" 
       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
           oasis-200401-wss-wssecurity-utility-1.0.xsd">
     <wsse:UsernameToken wsu:Id="UsernameToken-E0F7E1991F36AEE74F15194177192227">

         <wsse:Username>messageUsr</wsse:Username>
         <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/
               oasis-200401-wss-username-token-profile-1.0#PasswordText">
                 messagePword
         </wsse:Password>

         <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01
                oasis-200401-wss-soap-message-security-1.0#Base64Binary">
                  0ztu5ZBZogBtjTRoJBYnwQ==
           </wsse:Nonce>
         <wsu:Created>2018-02-23T20:28:39.222Z</wsu:Created>
     </wsse:UsernameToken>
   </wsse:Security>
</soapenv:Header>

To create the secure messaging client for an external system, the following information will be required:

• IRIS user credentials for message transmission

• System name and API key

• Clinical group identifier types and identifiers

• Provider identifier types and identifiers

• Patient identifier types and identifiers

• Message template key (for message template use only)

The table below will help you locate the information needed.

An   identifier type   is a general category of identifier, such as corporate ID. The identifier is the ID in the external system for an organization, clinical group, or provider.

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

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

2. Go to the   Setup   tab.

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

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

5. Under   Clinical Group Identifier Types , add one or more identifier types that Personal Community will accept from any external system for clinical groups.

6. Under   Organization Identifier Types , add one or more identifier types that Personal Community will accept from any external system for organizations.

7. Select   Apply   to save the changes.

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

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

To register an external system:

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

2. Go to the   Setup   tab.

3. On the   Setup   tab, select   External Systems . 

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

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

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

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

   • Enabled   — Required: whether the system can create or update clinical groups and providers.

   • Allow patient MPI search   — Not applicable for the Clinical Group and Provider API.

   • Allow message attachments   — Not applicable for the Clinical Group and Provider API.

   • Allow form requests   — Not applicable for the Clinical Group and Provider API.

   • Message Types   — Not applicable for the Clinical Group and Provider API.

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

   • Provider Identifier Types   — At least one entry is required for each assigning authority whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

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

   • Clinical Group Identifier Types   — At least one entry is required for each assigning authority whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

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

   • Organization Identifier Types   — At least one entry is required for the organization whose clinical groups and providers will be added or updated. An entity identifier type may be valid for more than one assigning authority. Select   Add   to create a new entry.

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

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

To add an identifier to a clinical group or provider manually:

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

2. Go to the   Setup   tab.

3. On the   Setup   tab, choose   Clinical Groups or Providers .

4. For each clinical group/provider that will use an external system to send messages to members:

   1. Select the appropriate row. This displays the   Clinical Group Details or Provider Details page for that entity.

   2. In the   Identifiers   section of the page, select   Add Identifier   to add a new identifier.

      1. In the   Type   drop-down menu, select the desired entity identifier type.

      2. In the   Name   drop-down menu, select the assigning authority for the clinical group/provider. This is likely the same assigning authority that you selected when registering your external system.

      3. In the   ID   field, enter the external system’s identifier for the clinical group/provider.

   3. Select   Save Identifiers   to save the new identifier, or   Discard Changes   to clear the unsaved identifier data and start over.

You can send messages to members based on events that occur in external systems. Pre-written content can be supplied for these messages with message templates.

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-settings.json   does not yet exist, copy   <hspc-home> /base/config/email-settings/en/email-settings.json   to the   custom   folder.

5. Add a key-value pair to   <hspc-home> /custom/config/email-settings/en/email-settings.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

   Following the example in the previous step, 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-settings.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.

To register a message template in the Workbench:

1. Log in to the Workbench as a user who has the   Configuration Manager   role. If forms will be associated with message templates, you must also have the   Forms 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, to add a message template, choose the   Add Message Template   button; to modify a message template, select the appropriate row. Both these actions display the   Message Template Details   page.

5. When adding a message template, complete the fields; when modifying a message template, change the values of the fields as required. The fields on this page are:

   • Name   — Required. The name by which the message template will be known in the Workbench.

   • Template key   — Required: you can use any alphanumeric string that will aid in the identification of this template.

   • Subject key   — Required..

   • Content key   — Required.

   • 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 for the patient, if any.

6.  When you are finished entering values, choose   Save   to save the data for the message template. To clear your changes and start over, choose   Discard Changes . Choose   Back   to leave the page without saving data.