The following diagram shows the processing path for Outbound HL7 v2.x Support.
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
Optional Extensions
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:
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.
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.
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.
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.
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"
}
}
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.
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.
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.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.
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;
}
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