On this page:

13.1HL7 v2.x Support: Inbound Messaging (to Smile CDR)

 

The following diagram shows the processing path for Inbound HL7 v2.x Support.

Inbound Support

To enable Inbound HL7 v2.x Support, create a module of type HL7 v2.x Listening Endpoint. This module type has many settings that affect the processing of various message types.

See Transactions for a list of supported message types.

13.1.1Callback Scripts

 

The listening endpoint makes several points in the processing pipeline available for modification using callback scripts.

The following diagram shows the processing flow when processing an incoming HL7 v2.x message.

Inbound Support

The following callback functions may be provided if desired. Note that it is possible but not neccessary to implement all functions.

These scripts may throw an exception, but this will result in an error and a processing failure being returned to the client.

13.1.2Function: onPreConvertHl7V2ToFhir(theMessage, theConversionResult)

 

If present, this method is called once for each message that is received on the HL7 v2.x Listening Endpoint, immediately after the message is logged to the transaction log and before the message is converted to FHIR for storage.

Parameters

This function takes the following parameters:

  • theMessage – This parameter is of type Hl7V2ReceivedMessage. The method can perform any manipulation required in order to make the received message conform to the Smile CDR HL7 v2.x structure and segment specifications.

  • theConversionResult – This parameter contains the result of an HL7 v2.x message runtime mapping. This parameter also exposes a function for adding messages to the conversion result. This parameter is of type Hl7V2ReceivedMessageConversionResult.

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: Adding Identifier Systems

A common issue when receiving HL7 v2.x messages from legacy systems is the lack of namespaces in identifiers, or having insufficiently descriptive identifiers.

For example, the PID-3 (Patient Identifier) field is used to store a Patient's identifers. In FHIR, an identifier should have at a minimum an identifier value and an identifier system.

These are mapped from PID-3-1 (Identifer Value) and PID-3-4 (Identifier System). Many sending systems will not populate a value in PID-3-4 however, or will populate a non-descriptive value such as a simple 2 letter mnemonic instead of a full URI as required by FHIR.

/**
 * This function will be called any time that a new message is received
 *
 * @param theMessage          The received HL7 v2.x message details
 * @param theConversionResult The result of an HL7 v2.x message runtime mapping
 */
function onPreConvertHl7V2ToFhir(theMessage, theConversionResult) {

	// This variable holds the actual HL7 v2.x message
	var rawMsg = theMessage.rawMessage;

	// Hardcode a Patient identifier system
	rawMsg['PID-3-4'] = 'http://acme.com/patients';

	// If the second repetition of PID-3 has a secondary identifier,
	// the following might be useful too:
	// rawMsg['PID-3[1]-4'] = 'http://acme.com/patientSecondaryIds';

	// Test if PV1 exists because not all ADT messages have this segment (but most do)
	if (rawMsg['PV1']) {

		// Hardcode an Encounter identifier system
		rawMsg['PV1-19-4-1'] = 'http://acme.com/visitNumbers';

		// Create a composite identifier for PV1-3
		var locationId = rawMsg['PV1-3-1'] + '-' + rawMsg['PV1-3-2'] + '-' + rawMsg['PV1-3-3'] + '-' + rawMsg['PV1-3-4'];
		rawMsg['PV1-3-10-1'] = locationId;                  // Location Identifier Value
		rawMsg['PV1-3-10-2'] = 'http://acme.com/locations'; // Location Identifier System

	}

}

13.1.3Function: onPostConvertHl7V2ToFhir(theMessage, theConversionResult)

 

If present, the onPostConvertHl7V2ToFhir(theMessage, theConversionResult) function will be invoked immediately following the conversion from HL7 v2.x to FHIR.

This function may make modifications to the resulting FHIR transaction Bundles before they are passed to the storage module for persisting.

The function also has access to the HL7 v2.x message in case it is needed.

Parameters

This function takes the following parameters:

  • theMessage – This parameter contains the received HL7 v2.x message, including any modifications made by the onPreConvertHl7V2ToFhir method. This parameter is of type Hl7V2ReceivedMessage. Note that modifications to the HL7 v2.x message do not have any effect here, as the conversion has already taken place.

  • theConversionResult – This parameter contains the FHIR transaction Bundles that were created during the conversion from HL7 v2.x. The resources may be modified by this function. This parameter also exposes a function for adding messages to the conversion result. This parameter is of type Hl7V2ReceivedMessageConversionResult.

Output

This function does not currently return a value, and any returned value will be ignored.

Example

The following example shows a function that creates a link (using a FHIR extension on Patient resources) between a child and their mother using the identifier found in PID-21 (Mother's Identifier). It creates a stub resource if one is not already present with the given identifier using the Smile CDR JavaScript FHIR REST API.

/**
 * This function will be called any time that a new message is received
 *
 * @param theMessage          The received HL7 v2.x message details
 * @param theConversionResult The resulting FHIR transaction(s)
 */
function onPostConvertHl7V2ToFhir(theMessage, theConversionResult) {

	// Loop through all transaction Bundles. Generally a conversion will produce 0..1
	// of them, but technically it is possible for one HL7 v2.x message to produce
	// more than one.
	theConversionResult.transactionBundles.forEach(function(nextBundle) {

		// Loop through any resulting patients. Again, this will typically only be
		// 0..1 but more is possible
		nextBundle.entryResources('Patient').forEach(function(nextPatient) {

			var mothersIdentifierValue = theMessage.rawMessage['PID-21-1'];
			var mothersIdentifierSystem = theMessage.rawMessage['PID-21-4'];
			Log.info("Mapping " + mothersIdentifierSystem + " - " + mothersIdentifierValue);

			if (mothersIdentifierValue && mothersIdentifierSystem) {

				// Search for any patients matching the mother's patient identifier
				var foundParentPatients = Fhir
					.search()
					.forResource('Patient')
					.whereToken('identifier', mothersIdentifierSystem, mothersIdentifierValue)
					.asList();

				var parentPatient;
				if (foundParentPatients.length > 0) {

					// If we found an existing match, that is the mother.
					parentPatient = foundParentPatients[0];

				} else {

					// If there is no Patient resource with the mother's identifier,
					// we'll create a stub patient so we have something to link to.
					parentPatient = ResourceBuilder.build('Patient');
					parentPatient.identifier.system = mothersIdentifierSystem;
					parentPatient.identifier.value = mothersIdentifierValue;
					Fhir.create(parentPatient);

				}

				// Add an extension to the Patient that has a reference to the mother
				nextPatient
					.addExtension('http://acme.com/ns/mother-reference')
					.valueReference = parentPatient;

			}

		});

	});

}

13.1.4Function addMessage(thePath, theMessageLevel, theIssue)

 

Function addMessage(thePath, theMessageLevel, theIssue) is exposed by parameter theConversionResult of type Hl7V2ReceivedMessageConversionResult. This method adds a message to the conversion result.

Note that messages of any level will appear in the transaction log, and messages with a level of ERROR will abort processing.

Parameters

This function takes the following parameters:

  • thePath – The path within a given HL7 v2.x message or FHIR resource with which the message is concerned (e.g. PID-3, Patient.identifier, etc.). This parameter is of type string.

  • theMessageLevel – Acceptable message levels are INFO, WARNING, and ERROR. This parameter is of type string.

  • theIssue – The message to be added to the conversion result. This parameter is of type string.

Output

This function does not currently return a value, and any returned value will be ignored.

Example

The following example illustrates use of this function.

/**
 * This function will be called any time that a new message is received
 *
 * @param theMessage          The received HL7 v2.x message details
 * @param theConversionResult The resulting FHIR transaction(s)
 */
function onPostConvertHl7V2ToFhir(theMessage, theConversionResult) {

	// Add an info-level message to the conversion result.
	var path = 'PID-18';
	var messageLevel = 'INFO';
	var issue = 'PID-18 (Patient Account Number) is good!';
	theConversionResult.addMessage(path, messageLevel, issue);

	// Add a warning-level message to the conversion result.
	var path = 'PID-19';
	var messageLevel = 'WARNING';
	var issue = 'PID-19 (SSN Number - Patient) is okay.';
	theConversionResult.addMessage(path, messageLevel, issue);

	// Add an error-level message to the conversion result.
	var path = 'PID-20';
	var messageLevel = 'ERROR';
	var issue = 'PID-20 (Driver\'s License Number - Patient) is bad!';
	theConversionResult.addMessage(path, messageLevel, issue);

}