Error Handling

From Wiki for HL7 Norge
Jump to: navigation, search

HL7 version 3 contains an elaborate mechanism for the identification of errors, warnings and informative messages. This page contains the highlights of this mechanism.

Overview

Errors, warnings and informative messages can be identified in multiple places; the use of the various options mainly depends on the type of issue one wants to identify.

  1. HTTP errors/SOAP faults: optional; errors related to the erroneous use of the HTTP and SOAP protocols
  2. Acknowledgement.TypeCode: mandatory indication in all responses if the message being responded to could be processed successfully or not.
  3. AcknowledgementDetail.code: optional; to identify errors related to syntactical issues upon receipt of the HL7 v3 message.
  4. DetectedIssueEvent.code: optional; to identify errors related to the violation of business-rules during the processing of the contents of the HL7 v3 message.
  5. QueryAck.queryResponseCode: conditional (mandatory in quuery responses); to identify errors related to the processing of queries or the interpretation of query parameters.

Note that all errors/issues are identified using a code (with additional text). The ability to use a code to identify an issue allows the receiver of the message to take automatic action to alleviate the issue. A textual error message (without a code) is useless when it comes to software processing logic.

1. HTTP/SOAP

  • Error category: errors related to the use of HTTP or SOAP protocols.
  • Error location: HTTP response, or SOAP faults

This page is silent about the use of HTTP errors. The use of the recommendations provided in the WS-I Basic Profile may be advisable.

The SOAP Body contains a fault element that can be used to convey errors at the SOAP level. This page (as of yet) is silent about the use of SOAP faults. The use of the recommendations provided in the WS-I Basic Profile may be advisable.

2. Acknowledgement.TypeCode

  • Error category: ability to process HL7 version 3 message
  • Error location: the TypeCode attribute in the Acknowledgement class of the Transmission Wrapper. TypeCode must be specified in all responses.

The most important attribute when it comes to the identification of errors in a response interaction is the Acknowledgement.typeCode (see Transmission Wrapper for a description of the attribute). The value of this attribute indicates whether or not the original interaction (the one being responded to) could be successfully processed or not.

typeCode indicates either success (the message could be processed), or failure (unable to process the message). Mainly for historic reasons there are four codes, two of which may ONLY be used in the Accept Acknowledgement interaction; the other two codes (AA, AE) are used in all other response interactions. AA and AE may NOT be used in Accept Acknowledgements.

Error/Success MCCI_IN000002UV02
Accept Acknowledgement
Other response interactions
Application Acknowledgement
Success CA AA
Error CE AE

Notes:

  1. Regardless of the value of the HL7 v3 typeCode the HTTP response SHALL be '200 OK'.
  2. In addition to the typeCode one may provide one or more AcknowledgementDetail and/or DetectedIssue classes (see below).
  3. In query responses one has to provide an additional queryResponseCode next to typeCode.

Examples
1. Accept Acknowledgement, with a CA typeCode

<MCCI_IN000002UV01 ITSVersion="XML_1.0" xmlns="urn:hl7-org:v3"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3">
    <id extension="34236" root="2.16.578.1.34.1.871.3"/>
    ...
    <acknowledgement>
       <typeCode code="CA"/>
          <targetMessage>
            <id extension="0806071541103" root="2.16.578.1.34.1.408.7"/>
          </targetMessage>
    </acknowledgement>

2. Application Acknowledgement, with an AE typeCode

<acknowledgement>
   <typeCode code="AE"/>
      <targetMessage>
        <id extension="0806071541103" root="2.16.578.1.34.1.408.7"/>
       </targetMessage>
</acknowledgement>

3. AcknowledgementDetail.code

  • Error category: errors and warnings related to syntactical issues upon receipt of the HL7 v3 message
  • Error location: the AcknowledgementDetail.code attribute in the Transmission Wrapper. This attribute is present in all response messages.

The AcknowledgementDetail class is a repeating construct in the Transmission Wrapper. Each class contains multiple attributes (typeCode, code, text) to identify the details of the error/warning. See Transmission Wrapper for documentation of the class structure. The key attribute is code. The standard coding system used is AcknowledgementDetailCode (defined by HL7); alternative project/application specific coding systems (with a different OID) may be used as well.

Examples using AcknowledgementDetailCode errors:
1. Error (AE), SYN102, with error text "Fødsesdato skal kun inneholde numre".

<acknowledgement>
    <typeCode code="AE"/>
    <acknowledgementDetail typeCode="E">
        <code code="SYN102" displayName="Datatype Error" 
              codeSystem="2.16.840.1.113883.5.1100"/>
        <text xsi:type="ST">Fødsesdato skal kun inneholde numre</text>
    </acknowledgementDetail>
    <targetMessage>
        <id extension="0806071541103" root="2.16.578.1.34.1.408.7"/>
    </targetMessage>
</acknowledgement>

2. Error (AE), Error (E) SYN101 (required attribute missing, see AcknowledgementDetailCode) and Warning (W) SYN103 (unknown code).

<acknowledgement>
    <typeCode code="AE"/>
    <acknowledgementDetail typeCode="E">
        <code code="SYN101" displayName="Datatype Error" 
              codeSystem="2.16.840.1.113883.5.1100"/>
    </acknowledgementDetail>
    <acknowledgementDetail typeCode="W">
        <code code="SYN103" displayName="Datatype Error" 
              codeSystem="2.16.840.1.113883.5.1100"/>
    </acknowledgementDetail>
    <targetMessage>
        <id extension="0806071541103" root="2.16.578.1.34.1.408.7"/>
    </targetMessage>
</acknowledgement>

4. DetectedIssueEvent.code

  • Error category: errors related to the violation of business-rules during the processing of the contents of the HL7 v3 message
  • Error location: the DetectedIssueEvent.code attribute in the ControlAct Wrapper. This attribute is present in all responses except the Accept Acknowledgement.

The reasonOf element can be used in the response interactions to give a reason why a request is rejected.

The coding system used to identify the error is mostly application/project specific. Examples include the PersonRegistryErrors coding system (defined by NHN).

Notes:

  1. HL7 also has a coding system for errors in this category; the coding system isn't used at the moment.

Examples (using a Helse Vest coding system):
1. AddNewPatient service. Reason for the reject of the message is that the patient already exists.

<reasonOf typeCode="RSON">
   <detectedIssueEvent moodCode="EVN" classCode="ALRT">
      <code code="KNOWNPAT" codeSystem="2.16.578.1.34.5.3" 
       displayName="Patient already known. This service requires a new patient." /> 
   </detectedIssueEvent>
</reasonOf>

2. Wrong query parameters; unable to execute the query

<reasonOf typeCode="RSON">
   <detectedIssueEvent moodCode="EVN" classCode="ALRT">
      <code code="VALIDATION" codeSystem="2.16.578.1.34.5.3" 
       displayName="insufficient parameters in query" /> 
   </detectedIssueEvent>
</reasonOf>

5. QueryAck.queryResponseCode

  • Error category: errors related to the processing of queries or the interpretation of query parameters
  • Error location: queryResponseCode attribute of the QueryAck class in the ControlAct Wrapper. The use of this attribute is limited to responses to Queries.

Examples of error in this category include missing parameters in a query, wrong parameter format (e.g. have a letter were there should be a number), or the use of an illegal F-/D-number format. In case of this category of parameter related errors:

  • QueryAck.queryResponseCode shall be set to QE (see ControlAct Wrapper for a description of this attribute), and AcknowledgementDetail.typeCode shall be set to AE (see Transmission Wrapper for a description of this attribute).

Examples:
1. The query could be successfully processed (OK).

<queryAck>
      <queryId extension="80622193108_11" root="2.16.578.1.34.1.805.1"/>
      <queryResponseCode code="OK"/>
      <resultCurrentQuantity value="2"/>
      <resultRemainingQuantity value="0"/>
</queryAck>

2. The query could not be successfully processed (QE - Query Error).

<queryAck>
      <queryId extension="80622193108_11" root="2.16.578.1.34.1.805.1"/>
      <queryResponseCode code="QE"/>
      <resultCurrentQuantity value="0"/>
      <resultRemainingQuantity value="0"/>
</queryAck>