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>

You will use the SendDirectCommunication method for event notifications.

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

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

Required fields to send a direct communication are:

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

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

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

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

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

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

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

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

   • If you want to use MPIID:

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

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

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

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

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

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

• ErrorCode   — The system code for the error.

• ErrorString   — A description of the error.

• direct-communication-patient-newdata- text .html
• direct-communication-patient-newdata- html .html
• direct-communication-patient-newdata- sms .html
• direct-communication-proxy-newdata- text .html
• direct-communication-proxy-newdata- html .html
• direct-communication-proxy-newdata- sms .html

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

3.1.1. Update Existing New Data Content Files

To customise the default new data content files:

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

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

   to

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

   Note

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

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

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

   to

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

3. Edit the custom copy of the files as required for your organization.

4. Refresh Content in the Workbench

   To refresh content:

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

   2. Go to the Content tab.

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

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

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

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

3.1.2. Create Additional Content Files for Workflows

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

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

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

   to

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

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

7. Refresh Content in the Workbench

   To refresh content:

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

   2. Go to the Content tab.

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

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

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

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

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

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

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

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

2. Go to the   Setup   tab.

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

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

5. Select   Apply   to save the changes.

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

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

To register an external system:

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

2. Go to the   Setup   tab.

3. On the   Setup   tab, select   External Systems . 

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

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

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

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

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

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

   • Allow message attachments   — Not applicable for event notifications .

   • Allow form requests   — Not applicable for  event notifications .

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

     • General –  Not applicable for event notifications .
     • Medical – Not applicable for  event notifications .
     • Reply – Not applicable for  event notifications .
     • Direct Communication – Make sure this checkbox is selected.

   • Authorization Settings   — Required. Saving the external system for the first time automatically generates a random alphanumeric string for   API Key . Make sure to share this value with the application developer who creates the external system’s notification framework.

     IMPORTANT

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

     
     

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

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

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

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

• IRIS user credentials for message transmission

• System name and API key

• Patient identifier types and identifiers

• Content key

The table below will help you locate the information needed.