Outbound: Default Resource Conversion
The default resource conversion mechanism uses subscription(s) on your business data resources to trigger the generation of appropriate HL7 v2.x messages.
For example, you might create a subscription on the Encounter resource which triggers ADT^A01 (Patient Admit). This is the easiest way to generate HL7 v2.x messages, but it can be limiting. This mode only supports automatic generation of messages using the conversions specified on the Transactions page.
This also means that messages are triggered strictly based on changes or creation of data, which is not a perfect match for the business meanings of the message transaction types defined in the HL7 v2.x specification. However, for many use cases this is not a problem and this mechanism has the advantage of being very easy to set up.
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
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",
"endpoint": "http://example.com:8080/fhir"
}
}
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",
"endpoint": "http://example.com:8080/fhir"
}
}
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