Client Documentation
Trier
Integration
Inbound Messages

Inbound Messaging

All inbound messages are sent to one entry-point in Trier using the MLLP protocol. Inbound messages can be split into two categories, pre-triage are the message sent from EDIS as responses to the Expects table workflow, and post-triage are the normal operational messages emited by both EDIS and webPAS.

MLLP Listener Service

The MLLP Listener service is a simple service that listens for inbound messages. It works by acting as a TCP server listening on a specific port. The connection is secured with TLS.

This service currently does the following:

  • [before] Convert an incoming message to a HL7 elements JSON object.
  • [before] Reads the message type and source app to determine the destination service.
  • [before] Calls the appropriate service using HTTP.
  • [custom] Stores the message in Azure object storage (in JSON format).
  • [after] Generate an acknowledgement message (in JSON) based on the response from the destination service.
  • [after] Convert the a HL7 elements JSON object to a HL7 message.
  • [after] Send the acknowledgement message back to the source app.

MLLP Listener Routing

Originally routing was going to be done within TriggerMesh but is now being done in the mllp-listener until TriggerMesh is working in Staging/Production.

trigger eventsending appdestination servicedestination endpointnotes
A05MEVencountershl7responseresponse to message sent by Trier (MEV)
A08MEVencountershl7responseresponse to message sent by Trier (MEV)
A04webPAS/EDISencountershl7updatenew patient
A08webPAS/EDISencountershl7updatevisit detail updates
A31webPAS/EDISencountershl7updatepatient detail updates
A03webPAS/EDISencountershl7dischargedischarge patient

Encounters Inbound Actions

The encounters service contains 3 custom actions for inbound HL7 messages. These actions expect the HL7 message to already be formatted in an HL7 elements JSON object.

These actions were originally meant to be called by TriggerMesh HTTP Target resources. The HTTP Target resource had a limitation where if the service it called returned a 500 or 400 error, no response event type would be generated (Essentially the HTTP Target would print a failure to its internal logs but not generate a response event as it normally would when a 200 code is received). Ideally, if the encounters action failed the event within TriggerMesh should persist and be picked up by another service that can handle the failed event. To try and mitigate this, these custom actions were written with try/catch blocks to catch any errors. The success property was used as a boolean flag to indicate if the action was successful or not. This way a response event would be created in TriggerMesh and a service can use the success property to capture any failures.

At the moment this isn't as necessary as TriggerMesh is not being used but the same strategy was maintained so it is ready for TriggerMesh integration.

HL7 Response

See responseFromSendHL7() in integration.ts of the encounters service.

If the message is an A05 this action will attempt to use the controlID to insert the newly generated "visit number" into the correct encounter as the edisID.

If the message is an A08 it will check for an error message. At the moment it doesn't do anything but on a 'triaged' error message the service should update the correct encounter (by edisID) and set that encounter to the triaged state to prevent any future A08 messages being sent to a visit (EDIS Expects table record) that can no longer receive any updates.

HL7 Update

This action does a lot mainly because it has to handle some unusual situations. See hl7UpdateFunc(), comments are included in the code to try and explain all the steps.

This function will attempt to match the inbound HL7 message with an existing encounter. Failing to do this, it will create a new encounter.

For both create and update a "formatter" function is invoked that translates a HL7 elements JSON object into an encounters object. This formatter function is found in formatters/encounterParseEHL7.js.

The main steps are:

  • Generate encounter object from EHL7
  • If update message, attempt to find encounter by edisID and then update it.
  • Otherwise try finding encounter by patient demographics (first name, last name, DOB, gender)
  • If no patient is found, create a new encounter & patient.
  • If a patient is found, check if there are any active encounters.
  • If there are active encounters, update the latest encounter.
  • If not, create a new encounter.

diagram

Notes

The location sent in the HL7 message is assumed to be correct. A db lookup in the locations container is done to find the correct location id. If the location id is not found, a new location is created.

Location information is only trusted from EDIS. If a location is sent in a message from webPAS, it is ignored.

The encounter is set to the triaged state automatically. If this encounter action is called the encounter must now be in the triaged state. TODO (actually this might be done TODO check) currently this is just set right now but on an encounter update it should only be set if the encounter was not already triaged. Otherwise the 'triaged' value (a epoch time) would keep getting updated each time an encounter update message is sent.

When hl7UpdateFunc() needs to create or update an encounter, it does so through the create and update actions. These actions are normally called directly from HTTP by a POST or PATCH request. The hl7UpdateFunc() already has access to the service object and can call these actions directly, thereby getting all the benefits of the action hooks (validation, logging, etc). To do this a new context object is generated and the input set to the encounter object. A fake identity must be generated as the hl7UpdateFunc() is not authorised. This identity is given the name of the sending app (EDIS or webPAS) and enough privelages to be able to fully create/update an encounter.

Some hooks in create/update actions were updated to recognise the fake identity and generate an activity item for the encounter when it is updated by this identity.

For a new encounter the infectious parameter is set to 'no' by default.

HL7 Discharge

See hl7DischargeFunc() in integration.ts of the encounters service. This action will find an encounter by visit number (edisID) and set the status to 'discharged'