Skip to main content

HealthShare Personal Community Messaging: Provider Initiated Messages from External Systems Setup Guide




1. Overview

An integral part of an organization's patient engagement strategy is the ability to provide patients with the ability to communicate with their providers.  Organizations may use the messaging capabilities of Personal Community to initiate conversations with their patients, providing them additional information or education about their care.

The Secure Messaging REST API allows for the sending of messages directly to a patient's Personal Community inbox. This API can be used by a trusted external system to send adhoc or automatically generated messages and attachments to patients.  

This API supports the sending of the following types of messages:

  • General messages to patients

  • Medical messages to patients

  • Replies to messages sent by patients (requires setting up and enabling patient initiated messages)

Personal Community supports this functionality with a SOAP API and a REST API.  All new integrations should use the REST API as this will be enhanced in the future.

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:

  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?

3.  Configuring Personal Community to Receive Messages from External Systems

Personal Community will need to be configured for external messaging when using either the Secure Messaging REST API or the Secure Messaging SOAP API.

3.1. Register an Assigning Authority in the Unified Care Record to Represent the External System

In most cases, the assigning authorities registered in the Unified Care Record are specific to a clinical group or a provider. These values are automatically synced into Personal Community.

Sending messages from an external system requires that you create an assigning authority in your Registry namespace that specifically represents the system.

To add an assigning authority:

  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. 

  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.

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

For the Secure Message APIs, you must assign the following role:

  • HSPortal_Role_API_Messaging

3.3. Add System Wide Identifiers in the Workbench

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:

  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.

3.4. Register the External System in the Workbench

Each external system that will be sending secure messages 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 messages.

    • Allow patient MPI search   — I f 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   — If selected, allows for the external system to send attachments with messages.

    • Allow form requests   — Forms are not currently supported with messaging. 

    • 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 –   Allows the external system to send general messages.
      • Medical   – Allows the external system to send medical messages.
      • Reply – Allows the external system to send reply messages.
      • Direct Communication   – Allows the external system to send direct notifications to a patient. 
    • 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.

    • Patient Identifier Types   — I f your team is using an identifier other than MPIID to locate patients for messaging, 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.

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

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

3.5. Create an Organization and Clinical Group to Represent the External System in the Workbench

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.

You must create an organization and clinical group to represent TrakCare:

  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. For example,   TC Education .

      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.

3.6. Configure the Clinical Group in the Workbench

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.

4. Configuring Content for Messages (Optional)

The Personal Community SOAP API is designed to handle both adhoc subject and message content (custom messages defined as send time), or to use message templates (template messages that are always sent for a given trigger).

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 or a member's proxy's inbox, if one exists

4.1. Create and Register a Template for a Secure Message

4.1.1. Create a Template File for the Secure Message

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

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

4.1.2. Register the Message Template in 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.

  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.

5. Enabling Messages in the Workbench

Organizations can control what types of messages patients can send.  The default workbench setting is set to enabled to allow for full functionality of the messaging feature. The setting may be changed by organizations if their provider messaging system may not be in place, or may not support different types of messaging
  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:

    • 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.
  1. After you have finished, select   Submit   at the bottom of the page to save your changes. 

6. Sending Messages from External Systems

6.1. Required Information for Secure Messaging

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 (Secure Messaging REST API) Application Developer Needs Value For (Secure Messaging SOAP API) Workbench Location Workbench UI Field
Username and password for system authentication Username and password for system authentication N/A N/A
system.name System.Name Setup  >  External Systems  >  External System Details Name
system.apiKey System.APIKey Setup  >  External Systems  >  External System Details API Key
sendingGroup.assigningAuthorityType 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 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 SendingGroup.ID Setup  >  Clinical Groups  >  Clinical Group Details The value of the   Identifiers  > External System ID field.
patient.patientIdentifier.assigningAuthorityType 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.
patient.patientIdentifier.assigningAuthorityCode 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 .
patient.patientIdentifier.id or patient.mpiid 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 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 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 SendingProvider.ID Setup  >  Providers  >  Provider Details The value of the   Identifiers  > External System ID field.
messageTemplateKey MessageTemplateKey Setup  >  Message Templates The value of the   Template key   field for the relevant template.

6.2. Sending Messages using the REST API

6.2.1. About the Secure Messages REST API

Swagger documentation for the Secure Messaging REST API is available   here .

6.2.2. Configuring Message Status Updates (Optional)

Personal Community can be configured to send updates as patients or their representatives open messages and message attachments. To use the functionality, sites will need to create a custom status update operation. Once this is completed, the message status update operation will need to be registered.

In the case that there are multiple external systems that wish to receive task status updates, a message status update operation is required for every external system. The message status update operation is stored against each external system's name.

6.2.2.1. Creating a Custom Message Status Update Processor

To create a new custom message status update class, follow the steps:

  1. Create a class that extends HSPortal.Production.Operation.AbstractMessageStatusUpdateOperation
  2. Override the method %OnMessageStatusUpdateRequest()

6.2.2.2. Configuring the Personal Community Production for Custom Message Status Updates

You must add the business operation associated with the message status update integration. 

To configure your Personal Community production:

  1. Logon to the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role.
  2. In your Personal Community namespace, go to the  Production Configuration   page. Specifically:
    1. Go to your Personal Community namespace by selecting  Switch   from the title bar and choosing its name in the namespace chooser.
    2. From the Management Portal, select  Interoperability > Configure > Production .
  3. Set up the business operation:
    1. On the  Production Configuration   page, under  Operations , select the   +   icon, to add a new business operation. This displays the  Business Operation Wizard .
    2. Select the Status Update class created in step 6.2.2.1 in the Operation Class drop down menu and set any defined properties as needed.

6.2.2.3.  Registering your Message Status Update Processor

Register your message status update processor with External System name and the custom operation name by using the $insert-status-update-operation API.

6.3. Sending Messages using the SOAP API

Note

Usage of the Secure Messaging REST API is encouraged over the Secure Messaging SOAP API. Any future enhancements to notification functionality will only be developed against the Secure Messaging REST API. The Secure Messaging SOAP API may eventually be deprecated.

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

6.3.2. Handling of Inbound Messages and Member Replies to Inbound Messages

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.

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

  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.

  9. TimeCreated   — The timestamp of the message in   yyyy - mm - dd   T   hh : mm : ss [. s ][ TZD ] format. 

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.

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.

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