HealthShare Personal Community External Messaging Setup Guide
1. Overview
This guide covers setup tasks relating to setting up messaging with an external system.
2. Required Information to Set Up Messaging with an External System
The list below may not be exhaustive, depending on the technical constraints of your specific external system.
For each external system, answer the following questions:
-
Regarding messages sent from Personal Community to the external system:
-
What APIs (if any) already exist?
-
Is a new interface needed on the external system to support this?
-
What message structures does the external system support as part of its existing workflows?
-
Are those structures extensible?
-
Are the message contents limited to plain text?
-
What structures does the system’s message format support?
-
-
Regarding messages sent from the external systems to Personal Community:
-
Can the system make calls to the Personal Community Secure Message API?
-
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.
-
Is there a need to send messages with pre-written content?
-
Are there events that should automatically trigger messages?
-
-
Regarding message flow:
-
Can providers initiate communication with members?
-
Can members respond to messages from providers?
-
-
Regarding recipient identification:
-
How does the external system identify members (that is, members of Personal Community)?
-
How does the external system identify its recipients such as providers or other staff?
-
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.)
-
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.)
-
-
Regarding message tracking:
-
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.)
-
-
Regarding varied implementations:
-
If a particular system is in use for multiple activities, does it have different constraints for each activity?
-
Does a particular system support different configurations, such as for different provider groups, which may require different behaviors for each group?
-
3. Sending Messages from Personal Community to an External System
This chapter describes background information on the Secure Messaging API, and the steps required to support sending messages from Personal Community to external systems.
To support sending messages from Personal Community to external systems, you must complete the following steps:
- Ascertain all of the required information to create each delivery interface.
- Create each delivery interface.
- Create the required business operations and business processes.
3.1. Overview of Message Routing within Personal Community
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:
-
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).
-
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.
-
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.
-
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.
-
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.
-
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):
-
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.
-
-
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.)
-
Sends the message to the external system using a protocol and transmission channel that the external system supports.
-
3.2. Creating the Delivery Interface
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:
-
Extend the HSPortal.Delivery.ExternalSystem class.
-
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.
-
-
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.
-
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.
3.3. Tying a Delivery Interface into the Personal Community Production
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:
-
Logon to the Management Portal for the production as a user with the %EnsRole_Administrator role or one with greater privileges.
-
Set up the business operation associated with the delivery interface:
-
In the Personal Community namespace, go to the Production Configuration page (from the Management Portal Home page, Interoperability > Configure > Production ).
-
On the Production Configuration page, under Operations , select the + icon, to add a new business operation. This displays information the Business Operation Wizard .
-
Complete the fields on the wizard, specifying the required information about the code that communicates with the external system.
-
Select OK to save the business operation.
-
-
Set up the business process associated with the delivery interface:
-
Also on the Production Configuration page, under Processes , select the + icon, to add a new business process. This displays information the Business Process Wizard .
-
Complete the fields on the wizard, specifying the required information about the delivery interface.
-
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.
3.4. Enabling Messages in the Workbench
-
Lo g into the Workbench as a user with the
Configuration Manager
role. -
Go to the Configuration Application page ( Setup > Configuration Application ) and select the Feature Control tab. In the activity pane, select Configure Messaging .
-
Select Edit Mode to make edits to the fields described in the following steps.
-
To the right of the Messaging box, ensure that the Enable checkbox is selected.
-
Once the Configure Messaging section is expanded, select from the current settings:
-
-
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.
-
Allow patient to send messages
- allows messaging functionality for members. Once selected, you must choose at least one of the following message types:
- After you have finished, select Submit at the bottom of the page to save your changes.
4. Sending Messages from an External System to Personal Community using the Secure Messaging API
You can use the Personal Community Secure Messaging API to send messages from an external system to a members inbox in the Personal Community public application.
4.1. About the Personal Community Secure Messaging API
The Personal Community Secure Messaging API is a set of SOAP web services that allows the following message types to be sent to Personal Community members from external systems:
-
General messages to members
-
Medical messages to members
-
Replies to messages sent by members
4.1.1. Handling of Inbound Messages and Member Replies to Inbound Messages
The Secure Messaging classes handle inbound SOAP messages from external systems as follows:
-
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.
-
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 ”.
-
The name and API key supplied for the external system are verified against those that were configured in the Workbench.
-
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.
-
Form keys and message template keys, if present, are validated to ensure they are present in Personal Community.
-
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.
-
-
After patient lookup succeeds, the identifiers for the sending/reply–to clinical group and sending provider are verified.
-
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.
-
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.
-
-
The delivery (or delivery failure) of the message is logged in the production.
-
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.
4.1.2. Sending a General or Medical Message
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:
-
System.Name — the name of the sending external system as it is registered in the Workbench. It can be a random alphanumeric string.
-
System.APIKey — the value of the API Key field for the sending external system as it is registered in the Workbench.
-
SendingGroup.AssigningAuthorityType — The identifier type configured for the sending clinical group in the Workbench.
-
SendingGroup.AssigningAuthorityCode — The assigning authority code for the clinical group configured in the Workbench.
-
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.
-
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.
-
-
-
Text — The body of the message. You must supply either body text or a message template: see the description of optional fields below.
-
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:
-
Log into the Management Portal and switch to your Personal Community namespace.
-
Go to System Explorer > SQL and select Go .
-
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.
4.1.3. Sending a Reply to a Message from a Member
The SendReply operation is identical to SendMedicalMessage and SendGeneralMessage operations, with one extra required field: ReplyToMessageID , which is the ID assigned by Personal Community to the patient’s reply message. The delivery interface and business operation responsible for routing the patient’s reply back to the external system can provide the reply message’s ID, which is the ID of the HSPortal.Production.Message.MessageWrapper object required by the SendMessage method. It is up to you to make that ID available to your SOAP request.
4.1.4. The Secure Messaging API WSDL
The WSDL for the Secure Messaging API can be found at the following URL:
<hostname>
:
<port-number>
/
csp
/
healthshare
/
<namespace>
/
HSPortal.Production.Service.APIMessageService.cls?WSDL
Authentication is required; the Workbench administrator can give you a set of credentials to do so. You can consume the WSDL using the IDE of your choice.
4.1.5. Authentication and Authorization
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>
4.1.6. Required Information for Secure Messaging Development
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.
Application Developer Needs Value For... | Workbench Location | Workbench UI Field |
---|---|---|
Username and password for system authentication | N/A | N/A |
System.Name | Setup > External Systems > External System Details | Name |
System.APIKey | Setup > External Systems > External System Details | API Key |
SendingGroup.
AssigningAuthorityType |
Setup > Clinical Groups > Clinical Group Details | The characters after the hyphen in the Identifiers > Type field. For example, the correct value to use from the field below is XX . |
SendingGroup.
AssigningAuthorityCode |
Setup > Clinical Groups > Clinical Group Details | The characters after the hyphen in the Identifiers > Name field. For example, the correct value to use from the field below is COR . |
SendingGroup.ID | Setup > Clinical Groups > Clinical Group Details | The value of the Identifiers > External System ID field. |
PatientIdentifier.
AssigningAuthorityType |
Setup > External Systems > External System Details | The characters after the hyphen in the Patient Identifier Types field for the clinical group that will be sending the message. For example, the patient identifier type for the clinical group represented by CLCL is MR , for medical record number. |
PatientIdentifier.
AssigningAuthorityCode |
Setup > External Systems > External System Details | The characters after the hyphen in the Patient Identifier Types —> Name field for the clinical group that will be sending the message. For example, the assigning authority code for the clinical group represented by CLCL is CLCL . |
PatientIdentifier.ID or
Patient.MPIID |
Tasks > Enroll Patient > Patient Details | The patient’s MPIID and other identifiers for each assigning authority are displayed on this page. |
SendingProvider.
AssigningAuthorityType |
Setup > Providers > Provider Details | The characters after the hyphen in the Identifiers > Type field. For example, the correct value to use from the field below is DN . |
SendingProvider.
AssigningAuthorityCode |
Setup > Providers > Provider Details | The characters after the hyphen in the Identifiers > Name field. For example, the correct value to use from the field below is CLCL . |
SendingProvider.ID | Setup > Providers > Provider Details | The value of the Identifiers > External System ID field. |
MessageTemplateKey | Setup > Message Templates | The value of the Template key field for the relevant template. |
4.2. Specifying Accepted Identifier Types
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.
Identifier Type | Identifier Examples |
---|---|
Corporate ID | “CSMC”, “Hospital Corporation” |
Doctor Number | 12345, Ash-019 |
To specify the acceptable identifier types for the use of any external system with your Personal Community instance:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, choose Site Configuration . This displays the Site Configuration Settings page.
-
Under Provider Identifier Types , add one or more identifier types that Personal Community will accept from any external system for providers.
-
Under Clinical Group Identifier Types , add one or more identifier types that Personal Community will accept from any external system for clinical groups.
-
Under Organization Identifier Types , add one or more identifier types that Personal Community will accept from any external system for organizations.
-
Select Apply to save the changes.
4.3. Registering an External System for Messaging
Each external system that will update clinical group and provider data in Personal Community must be registered in the Workbench.
If the external system already is registered in the Workbench for other APIs, you do not need to add another registration. However, be sure not to modify any existing settings unintentionally.
To register an external system:
-
Log in to the Workbench as a user who has the Configuration Manager role.
-
Go to the Setup tab.
-
On the Setup tab, select External Systems .
-
On the External Systems page, select Add External System .
-
Fill in the fields on this page as follows:
-
Name — Required. The name by which the external system will be known in the Workbench. This name will also be used in messages to and from the external system.
-
Description — Optional. A description of the external system.
-
Enabled — Required: 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.
-
-
-
When you are finished entering values, choose Save to save the data for the external system.
4.4. Adding Identifiers for Clinical Groups and Providers
External systems have their own identifiers for clinical groups and providers, and those identifiers are not known to Personal Community by default. For Personal Community to correctly display clinical group and provider information in messages to members, you must add the external system's identifiers in the Workbench.
To add an identifier to a clinical group or provider manually:
-
Log in to the Workbench as a user who has the Provider Manager role.
-
Go to the Setup tab.
-
On the Setup tab, choose Clinical Groups or Providers .
-
For each clinical group/provider that will use an external system to send messages to members:
-
Select the appropriate row. This displays the Clinical Group Details or Provider Details page for that entity.
-
In the Identifiers section of the page, select Add Identifier to add a new identifier.
-
In the Type drop-down menu, select the desired entity identifier type.
-
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.
-
In the ID field, enter the external system’s identifier for the clinical group/provider.
-
-
Select Save Identifiers to save the new identifier, or Discard Changes to clear the unsaved identifier data and start over.
-
4.5. Creating and Registering Message Templates
This section describes how to create message templates and then register them in the Workbench.
You can use message templates to:
-
Supply pre-written content for messages from external systems.
-
Automatically direct messages that use the template to a member’s inbox.
-
Automatically include form requests with messages that use the template.
4.5.1. Creating Message Templates
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:
-
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-settings.json does not yet exist, copy <hspc-home> /base/config/email-settings/en/email-settings.json to the custom folder.
-
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”
-
-
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.
4.5.2. Registering Message Templates in the Workbench
To register a message template in the Workbench:
-
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.
-
Go to the Setup tab.
-
On the Setup tab, choose Message Templates . This displays the Message Templates page.
-
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.
-
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.
-
- 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.