Sending HL7 Version 3 Query Messages

Appendix D - Sending HL7 Version 3 Messages

For Public Comment

This appendix and Appendix O of the ITI Technical Framework overlap in content. If you are reviewing this profile, we would like your feedback on the content of this appendix and of the ITI Appendix. Appendix O of the ITI Technical Framework can be found in the PIX/PDQ Version 3 Profile

HL7 Version 3 messages are sent in XML. Each message has information related to:

1. Messaging Infrastructure
2. Control Act
3. Domain Content

The first two components are described in greater detail below. Domain content is decribed in further detail within the IHE Profiles.

Message Infrastructure

This section of the message conveys information about the message itself, including:

• The message identity
• Creation time of the message
• The message type
• Processing controls on the message
• Identity of the sending and recieving systems
• The control act which is being conveyed in the message

An example message illustrating the message infrastructure elements is shown below.

<HL7Interaction xmlns="urn:hl7-org:v3" ITSVersion="XML_1.0"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <id root=' ' extension=' '/>
 <creationTime value=' '/>
 <interactionId extension='HL7Interaction' root='2.16.840.1.113883'/>
 <processingCode code='D|P|T'/>
 <processingModeCode code='A|T|I|R'/>
 <acceptAckCode code='AL|ER|NE'/>
 <receiver typeCode="RCV">
   <device determinerCode="INSTANCE">
     <id/>
     <name/>
     <desc/>
     <existenceTime><low value=' '/></existenceTime>
     <telecom value=' ' />
     <manufacturerModelName/>
     <softwareName/>
   </device>
 </receiver>
 <sender typeCode="SND">
   <device determinerCode="INSTANCE">
     <id/>
     <name/>
     <desc/>
     <existenceTime><low value=' '/></existenceTime>
     <telecom value=' ' />
     <manufacturerModelName/>
     <softwareName/>
   </device>
 </sender>
 <controlActProcess>
  See Control Act Process below
 </controlActProcess>
</HL7Interaction>

<HL7Interaction xmlns="urn:hl7-org:v3" ITSVersion="XML_1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> =

The HL7 Interaction being sent will control the name of the root element in the message. The namespace of this message shall be urn:hl7-org:v3, and the ITSVersion attribute shall be "XML_1.0".

<id root=' ' extension=' '/>

Each message shall be uniquely identified. The root attribute is required, the extension attribute may be used if the root attribute is insufficient to uniquely identify the message instance.

<creationTime value=' '/>

The creationTime indicates when the message was created, and shall be sent with a timestamp that is precise to at least 1/100th of a second.

<interactionId extension='HL7Interaction' root='2.16.840.1.113883'/>

The identifer for the interaction shall be sent. The extension value shall be valued with the HL7 Interaction identifier specified within the standard. The root attribute shall be set to the value 2.16.840.1.113883 to identify this as an HL7 interaction.

<processingCode code='D|P|T'/>

The processingCode element identifiers whether this message is being sent for debugging, production or training respectively. It shall be present and have one of the values D, P or T, as shown above.

<processingModeCode code='A|T|I|R'/>

The processingModeCode distinguishes the type of processing being performed, using the values A, T, I or R for Archive, current processing, Initial load, or Restore from archive respectively. This element shall be present and have one of the values shown above.

<acceptAckCode code='AL|ER|NE'/>

The acceptAckCode indicates whether the reciever wants to recieve an acknowledgement Always (AL), only on errors (ER), or never (NE). Unless reliable message transport has been established through some other mechanism, any message that would result in the potential alteration of clinical data shall be sent with the acceptAckCode set to AL, and any message that performs queries or is otherwise non-destructive should be set the value to 'ER' or 'AL'.

<receiver typeCode="RCV">
<sender typeCode='SND'/>

The reciever and sender elements shall be used to identify the systems responsible for recieving and sending the messages.

<id/>

The id element is required and identifies the sender or reciever of the message.

<name/>

The name element may be sent to provide a human readable name for the sender or reciever.

<existenceTime><low value=' '/></existenceTime>

The existenceTime element may be set by the sender on the sender element, or by the reciever on the reciever element to indicate the time at which the sending or recieving process was last started. The sender should not set this value for the reviever, and visa-versa.

<telecom value=' ' />

The telecommunications address for the sender and/or reciever may be sent. This address is the URL at which the sender or reciever is originating or recieving messages. The URL shall be the URL of the appropriate web service end-point.

<manufacturerModelName/>

The manufacturer model name may be set by the sender or reciever to indicate a human readable description of the manufacturer model name of the sending or recieving device. Once again, the senders and recievers should only set these values for themselves.

<softwareName/>

The software name may be set by the sender or reciever to indicate a human readable description of the software being used to send or recieve the message. Once again, the senders and recievers should only set these values for themselves.

Control Act Process

This section of the message identifies the action and provides information the business actors related to the transaction. This includes:

• The author or performer of the act
• The information recipients to who the information will be conveyed
• The domain content related to the act

 <controlActProcess moodCode="RQO|EVN">
   <id root=' ' extension=' '/>
   <code code='QUPC_TE043100UV'/>
   <effectiveTime value=' '/>
   <languageCode code=' '/>
   <authorOrPerformer typeCode=' '></authorOrPerformer>
   <informationRecipient typeCode=' '></informationRecipient>
   <!-- Performing a Query -->
   <queryByParameter>
     <statusCode code='new'/>
     <initialQuantity value=' '/>
     <initialQuantityCode code=' ' codeSystem='2.16.840.1.113883'>
     <parameterList>
       :
       Domain Content
     </parameterList>
   </queryByParameter>
   <!-- Returning Results -->
   <subject>
      :
      Domain Content
   </subject>
   <!-- Any response to a query (returning results, acknowledging a cancelation, or returning an error -->
   <queryAck>
     <queryId root=' ' extension=' '/>
     <statusCode code=' '/>
     <queryResponseCode code=' '/>
     <resultTotalQuantity value=' '/>
     <resultCurrentQuantity value=' '/>
     <resultRemainingQuantity value=' '/>
   </queryAck>
   <!-- Requesting more results or cancelling a query -->
   <queryContinuation>
     <queryId root=' ' extension=' '/>
     <statusCode code='waitContinuedQueryResponse|aborted'/>
     <startResultNumber value=' '/>
     <continuationQuantity value=' '/>
   </queryContinuation>
   </queryContinuation>
 </controlActProcess>

<controlActProcess moodCode="RQO|EVN">

The controlActProcess element is where information about the business act being performed is recorded. The moodCode is set to "RQO" by the sender to indicate a request to perform an action. The reciever will often return a new controlActProcess element in moodCode "EVN" to indicate that the act has been performed.

<id root=' ' extension=' '/>

Each control act may have a unique identifier, recorded in the id element. The root attribute must be present. The extension attribute may be present to further distinguish the identifier.

<code code='QUPC_TE043100UV'/>

The trigger event which caused the act to be transmitted shall be recorded in the code element.

<effectiveTime value=' '/>

The date and time of the trigger event shall be recorded in the effectiveTime of the control act. This is timestamp is distinct from the time of message transmission in the transmission wrapper.

<languageCode code=' '/>

The primary language used within the message content is identified in the languageCode element. This element shall be present.

<authorOrPerformer typeCode=' '></authorOrPerformer>

This element may be present to identify the business actors responsible for the message transmission.

<informationRecipient typeCode=' '></informationRecipient>

This element may be present to identify the business actors expected to recieve the result of the message.

Performing a Query

<queryByParameter>

For HL7 Version 3 messages that perform a query, the query is specified in the <queryByParameter> element.

<statusCode code='new'/>

When passing the parameter list, the <statusCode> element shall be recorded as above to indicate that this is a new query.

<initialQuantity value=' '/>

The <initialQuantity> element may be present to specify the initial number of data elements to be returned. The responder must send no more than the specified number of data elements in the response, but may send fewer than requested.

<initialQuantityCode code=' ' codeSystem='2.16.840.1.113883'>

The <initialQuantityCode> element indicates hoow responses are counted. This element must be specified when the <initialQuantity> element is present. It indicates the HL7 structures to count when determining the total number of data elements to return. The code is the identifier of the HL7 artifact to count (i.e., the R-MIM or C-MET identifier). Each query should indicate what structures are counted within the detail of the transaction. The rationale for counting based on HL7 structures is that each query is expected to return one or more "rows", and each row is expected to coorespond to an HL7 structure that is being returned.

<parameterList>

The <parameterList> data element shall be provided. This data element contains a domain specific set of parameters. These parameters will be described in the transaction detail.

Returning Results

<subject>
 Domain Content
</subject>

For typical HL7 version 3 messages, the domain content is accessible through the subject element, as is the domain content that is generated in response to a query.

<queryAck>

The queryAck element is transmitted in any message that is a response to a query, query continuation or query cancellation message.

<queryId root=' ' extension=' '/>

The queryId element shall be transmitted in a queryAck element. It shall contain an identifier that may be used in subsquent messages to obtain more results, or to cancel the query.

<statusCode code=' '/>

The statusCode element in the queryAck element indicates the status of the query. It may contain the value 'deliveredResponse' or 'aborted'. If the value is 'aborted', no additional messages should be sent to the data repository for the specified query.

<queryResponseCode code=' '/>

The queryResponseCode element indicates at a high level the results of performing the query. It may have the value 'OK' to indicate that the query was performed and has results. It may have the value 'NF' to indicate that the query was performed, but no results were located. Finally, it may have the value 'QE' to indicate that an error was detected in the incoming query message.

<resultTotalQuantity value=' '/>

The resultTotalQuantity element should be present, and if so, enumerates the number of results found. It shall be present once the last result has been located by the data repository. This element gives the count of the total number of results located by the query. When present, the resultRemainingQuantity element shall also be present.

<resultCurrentQuantity value=' '/>

The resultCurrentQuantity element shall be present, and shall enumerate number of results returned in the current response.

<resultRemainingQuantity value=' '/>

This resultRemainingQuantity element may be present, and shall be present if resultTotalQuantity is present. It shall enumerate the number of results that follow the results currently returned.

Continuation or Cancellation of a Query

<queryContinuation>

The queryContinuation element shall be sent in messages that are used to obtain more query results or cancel a current query.

<queryId root=' ' extension=' '/>

The identifier of the query to continue or cancel shall be reported in the queryId element.

<statusCode code='waitContinuedQueryResponse|aborted'/>

The statusCode element shall be sent, and indicates whether this is a continuation or cancellation of the query. If the query is to be continued, the code attribute shall be set to waitContinuedQueryResponse. If the query is to be canceled, it shall be set to aborted.

<startResultNumber value=' '/>

The startResultNumber element may be sent to indicate the query result to start returning from. If this element is sent, it shall be honored by the data repository. If this element is omitted, results will be sent that follow the last set of results sent. Results are numbered from 1, so setting this value to 1 will start with the first result returned. Setting this value to a number less than 1 will result in undefined application behavior.

<continuationQuantity value=' '/>

The continuationQuantity element shall be sent on cancelation requests, and shall have a value of 0. For continuation requests, this element may be sent to indicate the number of results that should be returned. The data repository may send fewer results than requested, but shall send no more than this value.