27.3HL7 v2.x Support: Outbound Messaging (from Smile CDR)
The following diagram shows the processing path for Outbound HL7 v2.x Support.
Getting Started
To enable Outbound HL7 v2.x Support, create a module of type HL7 v2.x Sending Endpoint. This module creates the endpoint that will transmit messages to an external system.
In order to enable automatic transmission of HL7 v2.x messages, a Subscription should be created in Smile CDR. This Subscription should resemble the following example:
{
"resourceType": "Subscription",
"id": "SUBSID",
"status": "requested",
"criteria": "DiagnosticReport?",
"channel": {
"extension": [
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-delivery-class",
"valueString": "ca.cdr.endpoint.hl7v2.out.deliverer.OutboundHl7V2SubscriptionDeliverer"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-sender-module-id",
"valueString": "hl7_sender"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-target-message-type",
"valueCode": "ORU^R01"
}
],
"type": "rest-hook"
}
}
Note the following extensions:
Required Extensions
- subscription-channel-rest-delivery-class: This must have the exact value shown above.
- subscription-channel-hl7v2-sender-module-id: This must contain the Module ID for a HL7 v2.x Sending Endpoint module on the same node as the FHIR Storage module.
Optional Extensions
- subscription-channel-hl7v2-target-message-type: (Optional) This extension supplies the HL7 v2.x message type that is created by this subscription. This may be omitted, in which case Smile CDR will attempt to use a sensible default for the resource type triggered by the Subscription.
27.3.1Sending Persisted Messages Verbatim
It is often the case (such as that of malformed messages) that one wishes to completely bypass any mapping or parsing of HL7 v2.x messages, and instead wishes to send them directly downstream as ingested. If one wishes to configure Smile to do this, one must set up inbound and outbound modules as usual, as well as enabling the following two settings:
- Store Original HL7v2 Message. This ensures V2 messages are stored verbatim on a MessageHeader resource.
- Forward Persisted Messages. This uses our internal subscription logic to watch for appropriate MessageHeader resources, scrapes the message off of it, and passes it back downstream.
Please note that this is only available when sending messages over HTTP due to the restrictions imposed by working with possibly invalid (read: un-parse-able) HL7 v2.x messages.
27.3.2ADT Workflow Mode
For many types of HL7 v2.x messages, it is easy to choose an appropriate FHIR Resource type that will always trigger that message. In the case of HL7 v2.x ADT messaging however, Smile CDR also offers a more nuanced mechanism called "workflow mode" where a set of rules are applied to determine which message type (and trigger) should be sent.
To enable workflow mode, you will need to create FHIR Subscriptions for the Patient and Encounter resources, using a target message type of ADT^WorkflowMode.
Note that the more workflow rules may be added in future releases of Smile CDR, so the specific triggers sent for a given scenario may change. If you are using workflow mode, please check this page when upgrading.
In ADT workflow mode, the following rules apply.
Patient Triggers
-
If a Patient is created (i.e. it has a version of
"1"), an ADT^A28 (Create Patient) transaction is sent. -
Otherwise, an ADT^A31 (Update Patient) transaction is sent.
Encounter Triggers
-
If an Encounter has a status (Encounter.status) value of
finished, an ADT^A03 (Discharge Patient / End Encounter) transaction is sent. -
If an Encounter has a version of
"1": -
Otherwise, an ADT^A08 (Update Visit) transaction is sent.
Subscription Resources
To enable ADT workflow mode, the following subscriptions must be created on your server:
Patient Subscription
{
"resourceType": "Subscription",
"id": "adt-workflow-patient",
"status": "requested",
"criteria": "Patient?",
"channel": {
"extension": [
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-delivery-class",
"valueString": "ca.cdr.endpoint.hl7v2.out.deliverer.OutboundHl7V2SubscriptionDeliverer"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-sender-module-id",
"valueString": "hl7_sender"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-target-message-type",
"valueCode": "ADT^WorkflowMode"
}
],
"type": "rest-hook"
}
}
Encounter Subscription
{
"resourceType": "Subscription",
"id": "adt-workflow-encounter",
"status": "requested",
"criteria": "Encounter?",
"channel": {
"extension": [
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-delivery-class",
"valueString": "ca.cdr.endpoint.hl7v2.out.deliverer.OutboundHl7V2SubscriptionDeliverer"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-sender-module-id",
"valueString": "hl7_sender"
},
{
"url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-hl7v2-target-message-type",
"valueCode": "ADT^WorkflowMode"
}
],
"type": "rest-hook"
}
}
27.3.3Enriching Message Conversion using Scripts
Smile CDR comes with a predefined conversion from FHIR resource models to HL7 v2.x. This conversion is intended to be sufficiently comprehensive to meet many use cases, but in many cases there are requirements to enrich the generated HL7 v2.x messages using other data. For example, a specific piece of data might be stored in a resource extension for a project, and that piece of data might be needed by recipients of the resulting HL7 v2.x messages.
In this case, a script may be used to enrich the message generation. The following functions are available.
27.3.4Function: onPostConvertFhirToHl7V2(theTriggerResource, theOutgoingMessage, theContext)
If present, this method is called once for each HL7 v2.x message that is generated. It is called after the built-in Smile CDR conversion has completed, but before the message is transmitted.
Parameters
This function takes the following parameters:
theTriggerResource– This parameter will contain the FHIR Resource that was the focus of this message generation.theOutgoingMessage– This parameter will contain the HL7 v2,x Message that was generated as a result of the conversion.theContext– This parameter is of type Hl7V2GeneratedMessageContext. It is not currently used but is provided for forwards compatibility.
Output
This function does not currently return a value, and any returned value will be ignored. It is possible however to modify the message that is passed in as an input parameter, making the parameter effectively an output as well.
Example: Copying Extension
The following example shows a field in the HL7 v2.x PID segment being copied using a value found in an extension within the FHIR resource.
/**
* This function will be called any time that a new HL7 v2.x message is generated
*
* @param theTriggerResource The FHIR resource that was the focus of this conversion
* @param theOutgoingMessage The generated HL7 v2.x message (may be modified)
* @param theContext The context object
*/
function onPostConvertFhirToHl7V2(theTriggerResource, theOutgoingMessage, theContext) {
var nationalityCodeableConcept = theTriggerResource
.getExtension('http://hl7.org/fhir/StructureDefinition/patient-nationality')
.getExtension('code')
.valueCodeableConcept;
theOutgoingMessage['*/PID-28-1'] = nationalityCodeableConcept.coding.code;
theOutgoingMessage['*/PID-28-2'] = nationalityCodeableConcept.coding.display;
theOutgoingMessage['*/PID-28-3'] = nationalityCodeableConcept.coding.system;
}
27.3.5Using Persisted MessageHeader Resources
It is possible (but not required) to use stored MessageHeader resources in Smile CDR FHIR Storage as the source for several fields in the HL7 v2.x MSH header. These fields include the Sending Application, Receiving Facility, etc.
The use-persisted-messageheaders setting may be enabled on the HL7 v2.x Sender module. When this setting is enabled, each time a resource (e.g. a DiagnosticReport) triggers an outbound message (e.g. an ORU^R01), Smile CDR will search for a MessageHeader resource with the focus resource as a target. If one is found, it will be used to populate fields in the HL7 v2.x message that is generated.
The following example shows a MessageHeader resource stored in FHIR Storage:
{
"resourceType": "MessageHeader",
"id": "999122",
"destination": [ {
"name": "Lab System",
"receiver": {
"identifier": {
"system": "http://acme.com",
"value": "116344"
}
}
} ],
"sender": {
"identifier": {
"system": "http://acme.com",
"value": "9837666"
}
},
"source": {
"name": "Hospital CDR"
},
"focus": [
{
"reference": "ProcedureRequest/8634"
}
]
}
This MessageHeader will result in an MSH segment similar to the following: MSH|^~\&|Hospital CDR|http://acme.com^9837666|Lab System|http://acme.com^116344|20180923190154.453+0330||ORU^R01^ORU_R01|8401|P|2.5