Minddistrict HL7 data exchange

The Health Level 7 (HL7) messaging standard is a well-known standard in electronic health systems. For more information about this standard see www.hl7.org and the Wikipedia entry on HL7.

The Minddistrict platform can process a number of different HL7 messages. Having an HL7 data exchange between an existing electronic health system and the Minddistrict platform makes it easier to administer clients, professionals and other entities in both systems.

Security

Because HL7 is a plain text message format and the information contained in the messages is highly sensitive we need a secure way of transmitting these messages over the internet. Minddistrict uses IPSEC VPN connections for this.

HL7 version

The Minddistrict platform can currently handle messages that adhere to the HL7 version 2.6 standard.

Message types

The Minddistrict platform can process two message types at the moment: ADT and MFN messages.

If the customer’s system uses different message types or message subtypes we can look into implementing those on the Minddistrict platform. We strive to make working with the Minddistrict platform and any systems it connects to as easy as possible. Being able to process more relevant incoming information contributes to this goal.

ADT: Admit Discharge Transfer

These messages are sent for client information. Adding a client, updating client information, deactivating a client, and merging clients are all possible using HL7 ADT messages. (ADT messages can be used for a number of other things, but these functions are the most interesting.)

The following ADT messages can currently be processed by the Minddistrict platform:

  • ADT A01 Admit a patient
  • ADT A03 Discharge a patient
  • ADT A04 Register a patient
  • ADT A08 Update patient information
  • ADT A14 Pending admit
  • ADT A18 Merge patient information
  • ADT A40 Merge patient
  • ADT A54 Change attending doctor

The responses to the different ADT messages would seem to be obvious, however because the HL7 standard is quite flexible it is possible to do non-obvious things. The description below is therefore by definition not complete, there’s some room for flexibility.

An important point to note is that the client id is the “foreign key” between an EHR system and the Minddistrict platform regarding clients. The client id is the uniquely identifying attribute that a client can be referenced to. This client id can take any form (numbers, letters or a combination of the two) as long as it’s unique. The client id is provided by the system sending the ADT messages. Clients in the Minddistrict platform also have an internal database id but that is not relevant to the HL7 data exchange.

ADT-A03 for deactivating a client

An ADT-A03 can be used to deactivate an existing client account in the Minddistrict platform.

The required field for an A03 message is:

  • client id

ADT-A04 for adding a client

An ADT-A04 is always used to create a client account. The Minddistrict platform can use this message to create either an active or an inactive client account. Normally a client gets an email when an account is created for them, but this is disabled in HL7 connections.

The required fields for an A04 message are:

  • first name
  • last name/family name
  • email address
  • gender
  • date of birth
  • client id

Because the Minddistrict platform requires an email address and this may not be present in the A04 a problem can occur: the A04 has been sent, but because there was no email address in it an account has not been created in the Minddistrict platform. In that case an error will be logged.

ADT-A04 messages are, by design, sent only once.

Additionally even though we do not recommend it, client accounts can be created using the following messages:

  • ADT-A01
  • ADT-A14

ADT-A14 is used by some EHR systems when an ehealth intervention is assigned to a client.

ADT-A08 for updating a client

The ADT-A08 message is normally used to update a client account. An A08 can also result in activating or deactivating the client account, depending on the specific content of the message and configuration settings.

The required fields for an A08 message are:

  • first name
  • last name/family name
  • email address
  • gender
  • date of birth
  • client id

An A08 message can also be used (abused) to create a client account. This can be a viable option if doing this reliably with other messages is not possible: for instance if an email address is not provided in an A04 message, and later on an update is made with an A08 message to include that missing email address, then all required information to create an account in the Minddistrict platform will be available in order to proceed. Whether or not this is done is depend on configuration settings.

Adding clients using an A08 does mean that the timing of adding the client could be confusing for the client. For example: they inform their therapist of their new phone number and all of a sudden they have an account for the Minddistrict platform.

Depending on channel configuration settings, the PID 29 and PID 30 are taken into consideration, resulting in deactivation of a client account for deceased patients.

ADT-A40 for merging two clients

Situations can occur when two (or more) client accounts are created for a same and unique person. This situation should obviously be resolved. The A40 MERGE message exists for this reason. An A40 message requests the merging of two client accounts into one, or in other words, the merging of the data of one client account into another and the subsequent removal of the former.

The required fields for an A40 message are:

  • client id to keep
  • client id to merge and remove

An A40 will at the same time update the client information.

Client accounts can be merged as well with the following messages:

  • ADT-A18

ADT-A54 for creating a client-therapist relation

An ADT-A54 message can be used to create a relation between an existing client to an existing therapist. Processing this message requires that both the client account and the therapist account exists in the Minddistrict platform beforehand.

The required fields for an A54 message are then:

  • client id
  • professional id

Client-therapist relations can be created as well with the following messages:

  • ADT-A14

ADT-A14 is used by some EHR systems when an ehealth intervention is assigned to a client.

MFN: Master File Notification

A subset of the MFN messages can be used to transfer information about therapists and other professionals.

The following MFN messages can currently be processed by the Minddistrict platform:

  • MFN-M02 Staff and Practitioner Master Files

The MFN-M02 messages can be used to:

  • add a professional
  • update a professional
  • deactivate a professional

By default the professionals added in this way have the role of therapist and no other roles. If the MFN message contains enough information it is possible to assign other roles as well.

An important point to note is that the professional id is the “foreign key” between an EHR system and the Minddistrict platform regarding professionals. The professional id is the uniquely identifying attribute that a professional can be referenced to. This professional id can take any form (numbers, letters or a combination of the two) as long as it’s unique. The professional id is provided by the system sending the MFN messages. Professionals in the Minddistrict platform also have an internal database id but that is not relevant to the HL7 data exchange.

Responses to HL7 messages

If an HL7 message is well-formed the receiving system will send an ACK message in return to signal that the message was received correctly. However, this does not mean that the contents of the message is correct or will lead to a change in the Minddistrict platform.

Logs and debugging problems

When the Minddistrict platform receives a message that is well-formed and can be processed correctly the content of the message can still generate an error. An example of this is when an ADT-A08 message is sent for a client that is unknown in the Minddistrict platform. The Minddistrict platform will try to update a client, but the client does not exist. This will generate an error. The errors generated in this way can be found inside of the Minddistrict platform and can be viewed by the application manager under “Configuration” > “HL7”.

When an action is taken in the EHR system and a result is expected but not seen in the Minddistrict platform, the interoperability report is the first, and easiest, place to check for errors.

Steps towards an HL7 data exchange

When a customer wants to have an HL7 data exchange with Minddistrict there are a number of steps to take. Here we give an example of how this process might proceed if Acme Health Company wants to connect their Electronic Health Record (EHR) system to the Minddistrict platform. The details will differ for each data exchange, but the broad outlines will be similar. In this example Acme is the only side of the data exchange that initiates the sending of HL7 messages.

Have a meeting

Acme and Minddistrict start with a meeting to discuss technical options and challenges. The discussion will get technical, including:

  • HL7 message semantics
  • business rules in both systems
  • security concerns

The people responsible for the network infrastructure are not required to be present at this point.

Determine scope

Which HL7 messages are going to be sent?

Acme specifies a list of HL7 messages that will be sent in the data exchange, and what effect they should have on data in the Minddistrict platform.

Which events in the HL7 sending system trigger which messages?

Commonly an EHR system sends out HL7 messages. Certain messages are sent as a consequence of certain events (a single event might cause multiple messages to be sent). Acme should determine which messages are sent when, to make sure that these will lead to the desired end result.

Test environment on customer side

Acme should make sure they have a testing environment to run integration tests with. This testing environment should not contain any production data; engineers at Minddistrict will need to view this data to work on the integration.

Test environment on the Minddistrict side

Minddistrict sets up a complete testing environment. The testing environment has accounts for all people relevant to the project, in particular for everyone involved at Acme.

Minddistrict sends the IP address and port of the testing environment to Acme.

Set up VPN in testing environment

Acme and Minddistrict work together to get the testing environment VPN set up.

To check that the VPN in the testing environment is working Acme sends a couple of HL7 messages through it. Minddistrict can check in the testing environment whether those messages were received.

Example messages

Acme sends a list of example HL7 messages to Minddistrict, in correctly encoded plain text files. For each message Acme will also state what the expected end result in the Minddistrict platform is.

Minddistrict will use these messages in development and in testing, so it’s important that the examples cover all variations that the data connection will encounter. Building a set of examples with good coverage of potential variations is not always easy; we include some advice below.

Processing the messages

After receiving the collection of example messages Minddistrict can start work on being able to correctly receive and process these messages. The amount of time this takes depends on several factors; in particular, if the messages require a change in the Minddistrict platform this will take longer.

In this step Minddistrict also creates the automated integration tests that prove the messages have the desired result in the Minddistrict platform. The tests are based on the example messages Acme has sent, which is why it’s important that the examples cover a wide range of cases. The integration tests are run during development, and at least once a day after deploying to production. If any of the moving parts change and this affects the connection these integration tests should pick up that failure and make sure the faulty change does not make it into production.

Compiling integration test cases

To show to all parties involved that the data exchange works as advertised, a number of manual integration tests should be run. These test cases are commonly run on the test-EHR system of the customer, which then sends HL7 messages to the Minddistrict test-setup where the desired result should then be visible in the Minddistrict platform.

Minddistrict works together with Acme to compile this list of test cases. The test cases should end up quite similar to the initial list of example messages; this isn’t surprising, since these tests, too, try to cover a wide range of edge cases.

Customer integration testing

Minddistrict will deploy the changes to the testing environment and inform Acme that they can start the manual integration tests in their testing environment. Acme can then take the list of manual integration tests and check that they pass.

If any tests do not pass, Acme will inform Minddistrict and both parties will investigate the cause and decide what action to take (e.g. alterations to the Minddistrict message-handling, or to the generation of messages from the Acme system, etc). Rerunning the integration tests may be necessary.

When all integration tests pass the data exchange connection can be moved to production. Acme should communicate this internally to any project leads or managers who might need to give confirmation before deploying to production.

Set up VPN in production environment

Acme and Minddistrict work together to get the production environment VPN set up.

To check that the VPN in the production environment is working Acme sends a couple of HL7 messages through it. Minddistrict can check in the production environment whether those messages were received.

Prepare deploy to production

Dependent on the message types that are sent various preparations may need to be done.

By default the Minddistrict platform allows users with certain roles to add and update clients, and users with other roles to add and update professionals. Depending on the types of HL7 messages that will be sent the manual management of certain types of users in the Minddistrict platform may no longer be necessary. Because of this the Minddistrict platform could be configured to no longer allow adding and editing of clients or professionals. This change may affect the work processes of the customer. Users of the systems should be informed of this in advance.

Acme revises their internal processes, and decides that there’s no longer a need to edit client or professional details directly in the Minddistrict platform: the details will be kept up to date via the HL7 data connection, instead. The new processes can only go into effect when the data connection is deployed, but Acme makes sure that everyone understands them well in advance.

Deploy to production

At an agreed time Minddistrict deploy the changes to production. Acme Health can then at their leisure deploy to production any necessary changes on their side. Usually this means reconfiguring an HL7 message distributor.

As part of the deployment, Minddistrict adjusts its monitoring tools to cover the new production system, and ensures that the integration tests are run automatically on a daily schedule.

Acme must now update the configuration of the Minddistrict platform to match the new situation. For example: if the source of client information in the Minddistrict platform is now the EHR system, the configuration “disallow adding/editing clients” should be enabled.

Acme should also perform a simple manual smoke test, to ensure the production environment works as expected.

Building a comprehensive set of example messages

To build a suite of tests Minddistrict needs a list of all HL7 messages the data exchange connection should be able to process, and the expected result in the Minddistrict platform for each one. Unlike a design specification, though, this list should not simply include each message type once: it’s important to cover all edge cases, so that automated testing can ensure that the connection correctly processes the full range of data it may be asked to handle. Covering enough edge cases needs knowledge both of the business rules of the EHR generating the messages and of the HL7 message format.

For example: suppose an EHR system has fields for a client’s family name, family name infix, married name, and married name infix. There is also a setting that indicates whether the client wants to be addressed by their family name, their married name, or a combination of both. Depending on if and how these fields are filled out a message from this system can contain quite a number of variations of surnames. The collection of example messages should contain enough permutations to ensure all cases in this regard are covered.

More generally, if a field is optional there should be example messages that omit it as well as examples where it is present.

An important message attribute to vary is the presence of non-ASCII characters. HL7 messages can be created using a number of character sets. To verify that the encoding is correctly set and the messages correctly processed it’s a good idea to add messages to the test suite that have non-ASCII characters like ä or ñ in some of their fields.

The HL7 message format uses so-called control characters to indicate the start and end of certain fields and sections. Which characters are used as control characters can be customized but usually they are: &^|~. To make sure these control characters are properly escaped by the EHR and read by the Minddistrict platform it’s also a good idea to add some example messages where one or more of these control characters are added in a field.