ControlAct Wrapper

From Wiki for HL7 Norge
Jump to: navigation, search

All HL7 version 3 interactions contain a Transmission Wrapper, an optional Trigger Event Control Act Wrapper (mostly referred to as the ControlAct Wrapper, present in all interactions except one: the Accept Acknowledgement) and a so-called Payload (in 90% of interactions there is exactly 1 payload, some interactions –notably responses to queries- may contain zero or multiple payloads).

The ControlAct wrapper has the aim to identify the Trigger Event (the underlying activity that caused the necessity for the information exchange) and the responsible party who caused the trigger event to happen. Example: If Dr. Smith decides to change the status of a radiology observation to 'final' (in HL7 v3 terms: from 'active' to 'completed') then this status change is the trigger event for sending a 'radiology result update' message. If Nurse Jones decides to send a query to the Folkeregistret then her decision to do so is the trigger event.

The ControlAct wrapper, if used in query interactions or responses thereto, also supports the specification of query parameters and the sending of query responses. Example: If one queries the Folkergistret using a Person-Name, a Birthdate and a Postalcode these three query parameters are modeled as part of the ControlAct wrapper. If the response to that query contains 5 matching records, that quantity (5) is modeled as part of the ControlAct wrapper as well. The matching records are Payload models and as such aren't part of the ControlAct wrapper.

Information Model

File:Cact main.png
Select thumbnail to enlarge; modified from NE2008

The controlActProcess class forms the entry class into the ControlAct wrapper model. The class represents the Trigger Event the underlying activity that caused the necessity for the information exchange). It contains the following elements:

Class Component Documentation
controlActProcess moodCode, classCode The controlActProcess identifies the person or software application that is responsible for triggering the interaction, i.e. the person/application that has sent the interaction.

@moodCode has the fixed value ‘EVN’. @classCode has the fixed value ‘CACT’.

The authorOrPerformer, assignedDevice and assignedPerson classes jointly identify the party responsible for causing the Trigger Event. These classes have the following elements:

Class Component Documentation
authorOrPerformer typeCode Identifies the sender (the author) of this interaction. For auditing purposes all interactions SHALL contain the identification of the author. The author can be either a person, or a software application.

@typeCode contains the fixed value ‘AUT’. The authorOrPerformer is identified as either an assignedDevice or a assignedPerson.

assignedPerson classCode Identifies a person. @classCode has the fixed value ‘ASSIGNED’ (either assignedPerson or assignedDevice must be present)
  id This class SHALL contain an identifier. The id contains a unique identification of a person. The attribute uses the II data type.

As long as there is no national identifier for all employees in healthcare the sender

  • SHALL send the 'software user identifier / login name' as assigned by the sending organization. Each software application that assigns 'user identifiers' will need to assign an OID to their own identification scheme.
  • SHOULD (additionally) send the HPR Number (with OID 2.16.578.1.12.4.1.4.4).
assignedDevice classCode Identifies a software application. Software applications can be the author of an interaction if the contents of the interaction (the payload) was generated automatically, e.g. whenever a software application generates a response to a query. @classCode contains the fixed value ‘ASSIGNED’

(either assignedDevice or assignedPerson must be present)

  id The id contains the unique identification of a software application. The attribute uses the II data type.

The subject act relationship associates zero or more Payload models with the ControlAct. The subject act relationship has no attributes associated with it.

Note: Any other classes/attributes not listed above, but shown in the diagram, are reserved for future use in Norway. Sending applications SHOULD not use these model elements; receiving applications SHALL nor produce an error if these model elements are present, and MAY ignore these model elements if present.

Detected issues

File:DetectedIssueEvent.png
Select thumbnail to enlarge; modified from NE2008

The reasonOf and DetectedIssueEvent classes can be used to identify "the reason for a trigger event". These classes are most often used (in responses) to identify errors/issues found in the message that is being responded to. The issues identified in the DetectedIssueEvent class have a business-processing characteristic (i.e. issues detected during the processing of the contents of a message, not during its syntax check). See Error Handling for additional details.

Examples:

  1. A laboratory receives an order to perform a "pregnancy test for a male patient". The laboratory systems responds with a "reject order" interaction; the DetectedIssueEvent class is used to identify the underlying reason (males can't be pregnant).
  2. A pharmacy system receives a prescription for medication X. The pharmacy system is aware that the patient is currently taking medication Y. For that reason, the pharmacy system sends a response message to reject the prescription; the DetectedIssueEvent class is used to identify the underlying reason (X has a contra-indication Y).
Class Component Documentation
reasonOf id This element occurs only in response interactions. It contains the identification of a business/process-level error. In the current project it is used to identify why a PatientRegistry.Add request could not be fulfilled. @typeCode has the fixed value ‘RSON’.
DetectedIssueEvent   Identifies one single issue/error.
  code this attribute identifies the kind of detected issue. For example: "medication contra-indication", or "Duplicate Patient ID".
@codeSystem contains the OID of the error code table, @code contains a code from that table, and @displayName contains a human readable description of the code. See Error Handling for additional details and the coding system.


Example:

<code code="KNOWNPAT" codeSystem="2.16.578.1.34.5.3" 
displayName="Patient already known. This service requires a new patient."/>
  value this attribute contains additional information about the specific issue. For example: "Medication X causes a conflict with medication Y", or "Patient ID 1234 was already created on 2009-09-01".
The value attribute has data type ANY, which is mostly overridden to be ST (string).


Example:

<value xsi:type="ST">Patient ID 1234 was already created on 2009-09-01</value>


Note: Any other classes/attributes not listed above, but shown in the diagram, are reserved for future use in Norway. Sending applications SHOULD not use these model elements; receiving applications SHALL nor produce an error if these model elements are present, and MAY ignore these model elements if present.

Queries/Response to queries

File:Cact qbp.png
Select thumbnail to enlarge; modified from NE2008

The queryByParameter class (and related parameter classes) is used to specify the details of a query. The class is only used in query messages. The queryByParameter class contains the follwoing elements:

Class Component Documentation
queryByParameter   The QueryByParameter class contains the specification of the query.
  queryId The id contains the unique identification of this query instance.

Implementation note: given the fact that all queries (in Norwegian implementations) lead to exactly one response: re-use same @extension/@root as present in the Message.id attribute of the Transmission Wrapper.

  statusCode @code contains the fixed value ‘new’
parameters value The individual parameters are documented on a service-by-service basis. Parameters serve to limit the number of matching records sent in response to the query.
File:Cact queryAck.png
Select thumbnail to enlarge; modified from NE2008


The queryAck class is used to convey the number of matching records returned in the response. This class is only used in messages that are a response to a query. The queryAck class contains the following elements:

Class Component Documentation
queryAck   This element only occurs in responses to queries. It contains information about the number of responses in the subject payload.
  queryId The id contains the unique identification of the original query instance (the value of the QueryByParameter.queryId attribute).
  queryResponseCode @code contains either ‘OK’ (if one or more records were found), ‘NF’ (if zero matching records were found), or ‘QE’ (if the query couldn’t be processed because of errors related to the query parameters – see Error Handling for details).
  resultCurrentQuantity Contains the number of responses/records in this response interaction. @value may be 0 if there were zero matching records.
  resultRemainingQuantity Contains the fixed value ‘0’.


Note: Any other classes/attributes not listed above, but shown in the diagram, are reserved for future use in Norway. Sending applications SHOULD not use these model elements; receiving applications SHALL nor produce an error if these model elements are present, and MAY ignore these model elements if present.

Examples

Note that in the examples below neither the Transmission Wrapper nor the payload model is shown.

TO-DO: Add HPR Num to example

1. The author of the interaction is a person (e.g. in queries, or request interactions):

<controlActProcess moodCode="EVN">
    <authorOrPerformer typeCode="AUT">
        <assignedPerson>
             <id extension="teneur" root="2.16.578.1.34.3.1"/>
              <id extension="1003040495" root="2.16.578.1.12.4.1.4.4"/>
         </assignedPerson>
     </authorOrPerformer>
     <subject>
     ....
     </subject>
</controlActProcess>

2. The author of the interaction is a software application (e.g. in an automated response to a query):

<controlActProcess moodCode="EVN">
     <authorOrPerformer typeCode="AUT">
        <assignedDevice>
           <id extension="922" root="2.16.578.1.34.1"/>
        </assignedDevice>
      </authorOrPerformer>
      <subject>
       ....
      </subject>
</controlActProcess>

3. Parameter specification in a query with QueryId 80622193108_11. The parameters themsleves aren't shown.

<queryByParameter>
     <queryId extension="80622193108_11" root="2.16.578.1.34.1.805.1"/>
     <statusCode code="new"/>
     <parameterList>
      ....
     </parameterList>
</queryByParameter>

4. Response to the query in example 3. The query could be successfully processed (OK) , with 2 matching records.

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