🔗 Source article (Salesforce): Click here
This tutorial will provide step-by-step examples to send and receive messages with the Unified Messaging SOAP-webservices.
Configuration
This tutorial assumes you have a running Hector or Unified Messaging running on http://localhost:8080/unified-messaging. Furthermore this installation should have a valid certificate configured on either eHealth acceptation or production.
The complete tutorial can be downloaded as a SOAP-UI project. UM-by-example.xml
You can check if the SOAP webervices are running on the following url:
http://localhost:8080/unified-messaging/services/
The default API token used is
12DAD342RD
Step-by-Step overview
In the tutorial we will go through the following steps to demonstrate an integration with Unified Messaging.
Step 1: Sending a message
Sending a message is done by posting a SendMessage SOAP request to http://localhost:8080/unified-messaging/services/UnifiedMessagingService/2_0
In the example below we are sending a simple text message about a patient to a doctor with ehealthidentifier 1403237. The message itself is base64 encoded in the body.
We are giving the message a ClientMessageId (my-message-id) this can be used by the integrator as a referenceId
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common" xmlns:ns2="urn:be:healthconnect:adr:1_0"> <soapenv:Header/> <soapenv:Body> <urn:SendMessageRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:Adr> <ns2:Addressee> <ns2:Quality>DOCTOR</ns2:Quality> <ns2:Identifier>14032237</ns2:Identifier> <ns2:EhboxIdType>NIHII</ns2:EhboxIdType> <ns2:Name>Example Institution</ns2:Name> </ns2:Addressee> <ns2:Subject>This is a test message</ns2:Subject> <ns2:Body> <!-- Base64 content of the body--> <ns2:Content>Rm9yd2FyZGVkIEJ5IEhlYWx0aENvbm5lY3QgU29mdHdhcmUu</ns2:Content> <ns2:Name>body.txt</ns2:Name> <ns2:MimeType>text/plain</ns2:MimeType> </ns2:Body> <ns2:Patient> <ns2:INSS>15030106774</ns2:INSS> <ns2:FirstName>MyTest</ns2:FirstName> <ns2:LastName>Patient</ns2:LastName> </ns2:Patient> <ns2:MetaData> <ns2:Key>encrypted</ns2:Key> <ns2:Value>true</ns2:Value> </ns2:MetaData> <ns2:ClientMessageId>my-message-id</ns2:ClientMessageId> </urn:Adr> </urn:SendMessageRequest> </soapenv:Body> </soapenv:Envelope>
This will generate the following response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <SendMessageResponse xmlns="urn:be:healthconnect:unifiedmessagingservice:1_0:common" xmlns:ns2="urn:be:healthconnect:adr:1_0"> <Status> <Code>100</Code> <Message>Success</Message> </Status> </SendMessageResponse> </soap:Body> </soap:Envelope>
This will not guarantee the message is succesfully sent, this only confirms the message is placed in the outbox. To check wheter the message is sent proceed to the following step : getMessageStatus.
Step 2: Get the status of the message
By using the messageId we can see the status of the message. For more info about status see Hector/ Unified-messaging.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:GetMessageStatusRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessageId>1000003643171</urn:MessageId> </urn:GetMessageStatusRequest> </soapenv:Body> </soapenv:Envelope>
Step 3: Get the sent message with a filter
The next request receives all messages in the SENT folder with 'my-unique-id' as ClientMessageID :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:GetFilteredMessagesRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessagesFilter> <urn:Folder>SENT</urn:Folder> <urn:ClientMessageId>my-message-id</urn:ClientMessageId> </urn:MessagesFilter> </urn:GetFilteredMessagesRequest> </soapenv:Body> </soapenv:Envelope>
The response :
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetFilteredMessagesResponse xmlns="urn:be:healthconnect:unifiedmessagingservice:1_0:common" xmlns:ns2="urn:be:healthconnect:adr:1_0"> <Status> <Code>100</Code> <Message>Success</Message> </Status> <Adr> <ns2:Sender> <ns2:Quality>HOSPITAL</ns2:Quality> <ns2:Identifier>71030229</ns2:Identifier> <ns2:EhboxIdType>NIHII</ns2:EhboxIdType> <ns2:Name>HC Institution</ns2:Name> <ns2:ApplicationId>HEALTHCONNECT</ns2:ApplicationId> </ns2:Sender> <ns2:Addressee> <ns2:Quality>DOCTOR</ns2:Quality> <ns2:Identifier>14032237</ns2:Identifier> <ns2:EhboxIdType>NIHII</ns2:EhboxIdType> <ns2:FirstName>Carl</ns2:FirstName> <ns2:LastName>Molemans</ns2:LastName> </ns2:Addressee> <ns2:Subject>This is a test message</ns2:Subject> <ns2:Patient> <ns2:INSS>15030106774</ns2:INSS> <ns2:FirstName>MyTest</ns2:FirstName> <ns2:LastName>Patient</ns2:LastName> </ns2:Patient> <ns2:MetaData> <ns2:Key>HC-MESSAGE</ns2:Key> <ns2:Value>true</ns2:Value> </ns2:MetaData> <ns2:MetaData> <ns2:Key>important</ns2:Key> <ns2:Value>false</ns2:Value> </ns2:MetaData> <ns2:MetaData> <ns2:Key>encrypted</ns2:Key> <ns2:Value>true</ns2:Value> </ns2:MetaData> <ns2:ClientMessageId>my-message-id</ns2:ClientMessageId> <ns2:MessageId>1000003643171</ns2:MessageId> </Adr> <hasMoreElements>false</hasMoreElements> </GetFilteredMessagesResponse> </soap:Body> </soap:Envelope>
Step 4: Processing the messages in inbox
When processing the inbox messages define first in which messages you are interested. Are all messages of importance or do you want to filter. The processing itself will happen in 2 steps. In the first step you need to ask the overview of downloadable messages, using a specific filter. In the second step, you can use the response of step1 to download a message using a specifid messageID.
[ IMAGE: image.png ]
Getting the overview of messages in your inbox for the first time
Example: get all the messages of the Inbox with functional type eforms
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:GetFilteredMessagesRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessagesFilter> <urn:Folder>INBOX</urn:Folder> <urn:FunctionalType>EFORMS</urn:FunctionalType> </urn:MessagesFilter> </urn:GetFilteredMessagesRequest> </soapenv:Body> </soapenv:Envelope>
Getting the overview of messages in your inbox once you already have succesfully downloaded and processed a message
Use the lastprocessedmessageid in the filter.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:GetFilteredMessagesRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessagesFilter> <urn:Folder>INBOX</urn:Folder> <urn:FunctionalType>EFORMS</urn:FunctionalType> <urn:Lastprocessedmessageid>1000003643171</urnLastprocessedmessageid> </urn:MessagesFilter> </urn:GetFilteredMessagesRequest> </soapenv:Body> </soapenv:Envelope>
This will return all messages where there are EFORMS attachments and that are more recent then message with messageID 1000003643171
Get one full message in the INBOX folder
To get a full message including attachments you should use the messageId and the INBOX folder.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:GetMessageRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessageId>1000003643171</urn:MessageId> <urn:Folder>INBOX</urn:Folder> </urn:GetMessageRequest> </soapenv:Body> </soapenv:Envelope>
The full message response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetMessageResponse xmlns="urn:be:healthconnect:unifiedmessagingservice:1_0:common" xmlns:ns2="urn:be:healthconnect:adr:1_0"> <Status> <Code>100</Code> <Message>Success</Message> </Status> <Adr> <ns2:Sender> <ns2:Quality>HOSPITAL</ns2:Quality> <ns2:Identifier>71030229</ns2:Identifier> <ns2:EhboxIdType>NIHII</ns2:EhboxIdType> <ns2:Name>HC Institution</ns2:Name> <ns2:ApplicationId>HEALTHCONNECT</ns2:ApplicationId> </ns2:Sender> <ns2:Addressee> <ns2:Quality>DOCTOR</ns2:Quality> <ns2:Identifier>14032237</ns2:Identifier> <ns2:EhboxIdType>NIHII</ns2:EhboxIdType> <ns2:FirstName>Carl</ns2:FirstName> <ns2:LastName>Molemans</ns2:LastName> </ns2:Addressee> <ns2:Subject>This is a test message</ns2:Subject> <ns2:Body> <ns2:Content>Rm9yd2FyZGVkIEJ5IEhlYWx0aENvbm5lY3QgU29mdHdhcmUu</ns2:Content> <ns2:Name>body.txt</ns2:Name> <ns2:MimeType>text/plain</ns2:MimeType> </ns2:Body> <ns2:Patient> <ns2:INSS>15030106774</ns2:INSS> <ns2:FirstName>MyTest</ns2:FirstName> <ns2:LastName>Patient</ns2:LastName> </ns2:Patient> <ns2:MetaData> <ns2:Key>important</ns2:Key> <ns2:Value>false</ns2:Value> </ns2:MetaData> <ns2:MetaData> <ns2:Key>HC-MESSAGE</ns2:Key> <ns2:Value>true</ns2:Value> </ns2:MetaData> <ns2:MetaData> <ns2:Key>encrypted</ns2:Key> <ns2:Value>true</ns2:Value> </ns2:MetaData> <ns2:ClientMessageId>my-message-id</ns2:ClientMessageId> <ns2:MessageId>1000003643171</ns2:MessageId> </Adr> </GetMessageResponse> </soap:Body> </soap:Envelope>
Change the status of the processed message and store the messageId
In case the status was succesfully processed and integrated change the status of the message to 'INTEGRATED_IN_EMD'. In case of an error change the status to 'FORWARDED_TO_EMD_FAILED". Store the messageId as the lastprocessedmessageid and use it in the following getfilteredmessageslist request.
The sender of the message will receive this messagestatus. This can be very useful for to optimize support interventions afterwards in order to investigate where in the chain the problem is.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:SetMessageStatusRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:Status>INTEGRATED_IN_EMD</urn:Status> <urn:MessageId>1000149410103</urn:MessageId> </urn:SetMessageStatusRequest> </soapenv:Body> </soapenv:Envelope>
Step 5: Delete a message
Optional step. Hector will remove automatically old messages.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:be:healthconnect:unifiedmessagingservice:1_0:common"> <soapenv:Header/> <soapenv:Body> <urn:DeleteMessageRequest> <urn:RequestInfo> <urn:ApplicationToken>12DAD342RD</urn:ApplicationToken> </urn:RequestInfo> <urn:MessageId>1000003643171</urn:MessageId> <urn:Folder>SENT</urn:Folder> </urn:DeleteMessageRequest> </soapenv:Body> </soapenv:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <DeleteMessageResponse xmlns="urn:be:healthconnect:unifiedmessagingservice:1_0:common" xmlns:ns2="urn:be:healthconnect:adr:1_0"> <Status> <Code>100</Code> <Message>Success</Message> </Status> </DeleteMessageResponse> </soap:Body> </soap:Envelope>