Markle | T2

Blog | Feeds | Publications

CONNECTING PROFESSIONALS

T2: Health Information Exchange: Architecture Implementation Guide

« Return to Markle Common Framework

Related Practice Areas

Additional Resources

Download T2: Health Information Exchange: Architecture Implementation Guide

4 General SOAP Message Structure

NHIN queries use a single SOAP service named “NHINQuery.” The two SOAP query operations for this service support an XML “wrapper” for sending an HL7 query via a SOAP message and an XML “wrapper” for receiving the response back in a SOAP message. Hence, the contents of the query message define the type of search performed and data returned rather than the SOAP operation.

The top-level SOAP <BODY> elements within the SOAP message are in the namespace “http://www.nhin.gov/messaging." The SOAP header always contains message routing information and data elements describing the user sending the query. The XML Namespaces section below describes the contents of the SOAP header.

At the topmost level of the SOAP message <BODY>, each request contains only the <NHINQuery> node. The WS-Basic Profile 1.0 requires a single node within the SOAP <BODY>, so there will never be a second node at this level. Within the <NHINQuery> node, we find two other nodes. One contains control information about the query settings and the other contains the actual query. For example, the topmost level of the PatientDataQuery SOAP message <BODY> looks like:

<soapenv:Body>
   <nhin:NHINQuery>
        <nhin:EvaluationSettings>
            <nhin:MaxResponseInterval>60</nhin:MaxResponseInterval>
            <nhin:ResponseStyle>I</nhin:ResponseStyle>
        </nhin:EvaluationSettings>
        <nhin:Query format=”HL7” version=”2.4”>
            <QBP_Z01 xmlns="urn:hl7-org:v2xml">
                …
            </ QBP_Z01 >
        </nhin:Query>
   </nhin:NHINQuery>
</soapenv:Body>

The <Query> node defines the information that is actually being requested. The SOAP service and operation are merely wrappers in which to pass this generic “query” specification. The format and version attributes define the format in which the query is expressed. Currently, only HL7 version 2.4 queries are supported. NHIN is considering support of HL7 version 3.0 as its use becomes more widespread.

At the topmost level of the SOAP message <BODY>, each response message also contains a single node. The <NHINResponse> node contains two data-bearing nodes, just like the NHINQuery node. One echoes the CLIENT control information and the other contains the query response. For example, the topmost level of the PatientDataQuery SOAP message <BODY> might look like:

<soapenv:Body xmlns:nhin=”http://www.nhin.gov/messaging”>
   <nhin:NHINResponse>
        <nhin:EvaluationSettings>
            <nhin:MaxResponseInterval>60</nhin:MaxResponseInterval>
            <nhin:ResponseStyle>I</nhin:ResponseStyle>
        </nhin:EvaluationSettings>
        <nhin:Response format=”HL7” version=”2.4”>
            < RSP_Z01 xmlns="urn:hl7-org:v2xml">
                …
            </ RSP_Z01 >
        </nhin:Response>
    </nhin:NHINResponse>
</soapenv:Body>

All NHIN queries are expressed as HL7 2.4 messages and segments. Most of the query responses are also standard HL7 messages and are represented in a single <Response> node. However, queries that return medication history do so in the NCPDP Scripts 8.1 XML format (an XML representation of NCPDP) rather than in HL7. To accommodate this, and future, mixed data representations within a query response, multiple <Response> nodes are permitted. Data formats are not mixed within one <Response> node. For example, an HL7 response will never be intermixed with an NCPDP Scripts response, although they may be wrapped within the same query response message.

Every <EvaluationSettings> node has the same schema definition across all messages, as documented in Appendix C. Values within this node define general query processing settings, like the maximum time interval before the querying system expects a response, as per the example above.

We define the following SOAP operations, which cover the current use cases:

Operation	Description
PatientDataQuery	Requests patient health data for a single patient.
PatientDataQueryResponse	Returns the requested patient health data for all registrations found for the specified person.

4.1 XML Namespaces

NHIN query messages currently use two namespaces for NHIN-specific elements and attributes, one for the query data and one for the header attributes used to route the asynchronous query responses (see next section of this document). The header attributes used for response routing are defined in the “http://www.nhin.gov/addressing” namespace, which is qualified as “nhinWsa:” in the examples used in this document. (Note that nhin.gov is a URI but not a URL; we have adopted it simply to guarantee uniqueness of namespace.) All other NHIN-specific elements and attributes are defined in the “http://www.nhin.gov/messaging” namespace, which we qualify with “nhin:” in the examples in this document. The SOAP envelope tags for a typical NHIN query might look like:

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
        xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:nhinWsa=”http://www.nhin.gov/addressing”
        xmlns nhin=”http://www.nhin.gov/messaging” >
</soapenv:Envelope>

4.2 Asynchronous Query-and-Response Messaging Between ISBs

We expect that the WS-Addressing 1.0 W3C Recommendation will become a W3C standard within the next year. We believe it will enjoy widespread use following standardization, and that tools for implementing it will then proliferate. Of special interest to the NHIN project are the WS-Addressing 1.0 controls (in the SOAP header) for defining an asynchronous SOAP conversation, since all initial NHIN SOAP conversations will be asynchronous.

However, NHIN is not comfortable making WS-Addressing 1.0 a requirement for initial NHIN participants. WS-Addressing is not easily implemented across SOAP server platforms, at least in the versions that are currently in wide use. Newer implementations, as they currently exist, would make it difficult to communicate with NHIN servers on their present SOAP server platforms. Hence, NHIN defines its asynchronous conversations using a subset of the tag names that WS-Addressing would use, but in NHIN’s own XML “namespace.” The NHIN architecture also defines its logically asynchronous query-and-reply conversation as a pair of physically synchronous SOAP conversations, one conversation for the query and one for the response. These variances from real WS-Addressing enable immediate use of the NHIN message infrastructure, but simplify the move to full WS-Addressing in the future. For now, a WS-Addressing-style value, in the SOAP message header, defines where the asynchronous query response will be sent by the NHIN server.

In an asynchronous NHIN query and reply, a NHIN client sends a query to an NHIN server in a SOAP message. The NHIN server immediately returns a SOAP “ACK” message (see Appendix F) to the NHIN client, signifying that the query has been received and understood. This initial SOAP conversation, representing the NHIN “query”, is now complete as far as the SOAP servers are concerned. Once the NHIN server has read and formatted the query results, it initiates a new SOAP conversation. The NHIN server sends the query response to the destination it found in the node of the original SOAP query message. Once the NHIN client receives the query response, it returns a SOAP “ACK” to the NHIN server. This completes the NHIN “response” SOAP conversation. To summarize, the NHIN logical query-and-respond conversation is implemented as two physical SOAP conversations: a query-and-ACK SOAP conversation followed by a separate respond-and-ACK SOAP conversation. This logically asynchronous conversation can be implemented on virtually all SOAP server platforms.

Suppose the ISB receives a message whose SOAP message begins with the following:

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
        xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:nhinWsa=”http://www.nhin.gov/addressing”
        xmlns nhin=”http://www.nhin.gov/messaging” >
   <soapenv:Header>
         <nhinWsa:MessageId>1234</nhinWsa:MessageId>
          <nhinWsa:ReplyTo>
        <nhinWsa:Address>https://1.2.3.4:8443/myapp/services/NHINQuery</nhinWsa:Address>
         </nhinWsa:ReplyTo>
   </soapenv:Header>

The ISB will send the NHINPatientDataResponse query response to the URL http://1.2.3.4:8080/myapp/services/NHINPatientDataResponse.

An example of a SOAP header with full NHIN addressing information follows:

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
        xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:nhinWsa=”http://www.nhin.gov/addressing”
        xmlns nhin=”http://www.nhin.gov/messaging” >
   <soapenv:Header>
        <nhinWsa:MessageId>1234</nhinWsa:MessageId>
        <nhinWsa:ReplyTo>
            <nhinWsa:Address>
            https://1.2.3.4:8443/myapp/services/NHINQuery
    </nhinWsa:Address>
        </nhinWsa:ReplyTo>
   </soapenv:Header>
   <soapenv:Body>
        …
   </soapenv:Body>
</soapenv:Envelope>

4.3 Identifying the Query User

Every query must identify the user who initiated the query, as per HIPAA guidelines, and log the user identification along with a description of the data that was accessed. The Inter-SNO Bridge service that receives the NHIN query trusts that the user was properly authenticated by the sending SNO. The mechanism for reaching that understanding is beyond the scope of this document.

We consulted the OASIS SAML specification to find the format in which it represents username information in the SOAP header, hoping to use their format. However, the “UsernameToken” 1.0 profile does not specify some attributes that we require, like the user’s full name in any concrete manner. Instead then, NHIN queries identify the query-requesting user in an NHIN-specific node within the SOAP header. NHIN plans to harmonize its user identification format with the SAML specification in the future. Currently though, the query user’s identity in the node is in the same data format that one would use to retrieve the access log information about that query user. That is, the query user is defined in the same format that would be found within an HL7 query or response.

NHIN queries represent the query-requesting user in a familiar HL7 2.4 XCN data type. An example follows:

<nhin:Security>
       <nhin:QueryRequestor>
           <XCN.1>JoeUser</CX.1>
       <XCN.2>Smith</XCN.2>
           <XCN.3>Joseph</XCN.3>
           <XCN.9>
               <HD.1>ST ELSEWHERE HOSPITAL Users</HD.1>
           <HD.2>USERID</HD.2>
           <HD.3>ST ELSEWHERE HOSPITAL</HD.3>
         </XCN.9>
           <XCN.13>EI</XCN.13>
       <XCN.14>
               <HD.1>ST ELSEWHERE HOSPITAL</HD.1>
           </XCN.14>
       </nhin:QueryRequestor>
</nhin:Security>

This is the same manner in which that user would have been represented within any of the HL7 2.4 messages sent across the NHIN.

4.4 NHIN Server Error Handling

Upon receipt of a request message from a CLIENT system, the SERVER acknowledges receipt of the message, validates the syntax of the incoming message, and asynchronously starts processing the message. If an error occurs after the “valid message” indication, the error information must be returned to the CLIENT system in the asynchronous SOAP response. If the error occurs before the SERVER validates the query message and responds with the “ACK” SOAP message, a SOAP Fault can be generated. Appendix D lists the potential fault codes returned and the information that should be included in the accompanying detail.

When an error/fault occurs after the NHIN server has sent its ACK back to the NHIN client, it is impossible (or at least very difficult) to return a SOAP Fault using a current SOAP server. Therefore, the error/fault must be sent back in the asynchronous query response message. In that message, the MSA.1 (ACKNOWLEDGMENT CODE) value is “AE” (Application Error) instead of “AA.” A descriptive fault message is also returned in the MSA.3 (TEXT MESSAGE).

The NHIN SERVER can encounter different types of errors once it receives a valid query message. An application error may occur within the SERVER itself. A SOAP fault may occur when the SERVER tries to send a SOAP message to another node within its SNO when that system is down, appropriate security certificates are not in place, network communications fail, the service rejects the message due a syntax error, etc. Finally, a true application error may occur inside the SNO node that is doing the query resolution on behalf of the NHIN server.

In the first case, the NHIN Server must create its own error code and error message. In the second case, the server retrieves the SOAP fault code and error message from the SOAP fault. In the third case, the server recovers the application error information from the response message it gets back from the SNO node. In any case, the NHIN server ends up with an error code and an error message that are sent back to the CLIENT within the MSA segment of the query response.