Submitting OLIS Messages

How to package an OLIS request and how to decode an OLIS response


Message Submission Overview

Please also refer to section 11.5 "Message Exchange Overview" of the OLIS Standard

 

OLIS is implemented as a web service. The web service has a single method, OLISRequest, and it synchronously returns a single response, OLISResponse. The request contains the HL7 ER7 content for any of the OLIS operations (order, update, query, etc.) and the response contains the corresponding HL7 ER7 response to the request.

 

  • To submit a request to OLIS, an EMR/HIS/LIS system submits a valid OLIS HL7 ER7 message request, OLIS then processes the request and returns a response to the caller over the same communications channel (i.e. it is a synchronous transaction).
  • The maximum message size that can be sent is 5MB. Note that this size includes all overhead associated with the message (the outer SOAP layer, digital signing, base64 encoding, etc.) – the largest HL7 ER7 message that can be sent is approximately 3.5MB.  Larger messages will be rejected.
  • OLIS request messages consist of two layers:
    • an inner layer (Request) that contains the HL7 message
    • an outer layer (HIALRequest) that contains the inner layer encoded and digitally signed
  • OLIS HL7 ER7 message preperation (See Sending/Receiving System Procedures and the diagram below):  The message preparation generally will include proper signing *, encoding, and placing of the prepared OLIS message into a HIALRequest (SOAP) message for transportation.
  • The HIALRequest message is transmitted using SOAP to the OLIS Web Service OLISRequest method over the HTTPS (SSL/TLS over HTTP) transport protocol. This is a mutually authenticated session, with each party verifying the identity of the other through the use of digital certificates.
  • After processing the request message, OLIS will return a response message to the caller.
  • OLIS response messages are the same digitally signed format as the request messages (with all instances of Request replaced with Response). The only difference is that the innermost layer of the response message may contain an error collection if errors were encountered in the processing of the message.
  • Note: The outer signature layer obscures the inner layer signature*, therefore, once the signature has been decoded and validated, an additional XML parsing of the signed data (which is XML format) must be performed to access the HL7 payload.

 * the digital signing is NOT applicable for this particular services offering, but is discussed here for the purpose of understanding the full end-to-end process in production.  In production however, the OLIS web service call is made over a mutually authenticated SSL/TLS connection. Digital certificates issued by eHealth Ontario are used by the SSL/TLS protocol on both ends of the web service communication to mutually authenticate and encrypt all communication to and from OLIS.  The data passed to the OLISRequest method and the data returned in the response is digitally signed. It is the responsibility of the client application to digitally sign the OLIS request data and to verify the digital signatures on responses from the OLIS system.

 

Sending System Procedure

 This procedure is followed by the EMR/HIS/LIS to create an OLIS message. 

  1. Create an OLIS HL7 ER7 message. Remember the MSH.10 value; it will be needed in step 6.
  2. Place the HL7 message in the Content element of the Request XML message (refer to the Request XML Schema).
  3. FOR THE CURRENT OLIS SERVICE OFFERING THIS DOES NOT APPLY TO LITE SERVICES:  Digitally sign the Request message using a PKCS#7 format signature using a cryptographic toolkit. The Request XML, which contains the HL7 ER7, will be included within the signature.
  4. For the current OLIS Service offering, Base64 (ASCII) encode Request XML message, (for production, base64 encode the digital signature).  The message now will be encoded into ASCII characters.
  5. Create a SignedRequest message and embed the encoded Request message/digital signature in the SignedData element.
  6. Create a HIALRequest message and set the SignedRequest element to the SignedRequest message. Set the ClientTransactionID element to MSH.10 value from the HL7 ER7 (Step 1).
  7. Call the OLISRequest web method on the OLIS web service passing the HIALRequest message as the parameter.
  8. The SOAP message will travel over a mutually authenticated HTTPS connection to the OLIS system.
  9. When the web services method call returns, follow the steps in the Receiving System Procedure to obtain the HL7 response message.

  

  

Client Transaction Identifier

Client Transaction IDs are unique, per-transaction identifiers that are located in the outermost layer of the HIALRequest and HIALResponse XML messages. Client systems set the transaction ID and the same transaction ID is returned in the response message.

Client systems must set the Client Transaction ID to the same value as that contained in the MSH.10 Message Control ID field in the embedded HL7 ER7 message.

 

Receiving System Procedure

 This procedure is followed by the EMR/HIS/LIS when a SOAP message is returned. 

  1. Trap any XML SOAP faults (exceptions) that occur. If there are errors, stop.
  2. The returned data is a HIALResponse XML message.
  3. The ClientTransactionID in the HIALResponse will match that which was set when the message was sent. The SignedResponse element contains the Response message (* digitally signed response for production message).
  4. From the SignedResponse, extract the encoded Response message (* digital signature for production message) from its SignedData element.
  5. Base64-decode the Response message/digital signature. If there are errors, stop.
  6. * Verify the digital signature using a PKCS#7 cryptographic toolkit. If the signature verification fails, stop processing and return an error.
  7. * Extract the signed data (XML) from the digital signature – this is a Response message.
  8. Check for errors as indicated by the Response Errors array element
  9. If there are no errors, extract the HL7 ER7 from the Content element.
  10. Process the HL7 ER7 response.

  * the inner layer signing is NOT applicable for this particular services offering, but is discussed here for the purpose of understanding the full end-to-end process in production

 

Errors

There are three different types of errors that can be returned from OLIS, each corresponding to the three layers of message formatting: SOAP, XML and HL7. These errors are indicated in SOAP Faults, XML Error elements, and HL7 error segments, respectively. These errors are exclusive of one another. i.e.  if there is a SOAP Fault then there will not be a error included in the XML error field nor an HL7 error, etc.

 

Faults

XML SOAP faults result when a high level error occurs. Examples of these include: when a transaction is too large, when an unrecoverable web services error occurs, when a SOAP message can’t be parsed, etc.

 

XML Error Codes (Response Errors)

If there are problems processing the XML message (the digital signature is missing/corrupted/invalid, a virus is detected, etc.), then an error will be indicated in the Response errors element in the returned XML.

 

Errors indicated in HL7 ERR Segments

If there are OLIS application-specific errors (wrong format of HL7, incorrect values in HL7 fields, an invalid OLIS query, etc.), then these will be indicated in the HL7 ERR segments returned by OLIS.

 

For more details see OLIS XML Message Definitions page