hl7_transform

hl7_transform is a tool to modify and transform HL7 messages using a mapping scheme. It can be used as a standalone tool or as a Python library.

How to use

Install hl7_transform from Pypi:

pip install hl7_transform

Once installed, you can run hl7_transform script in your shell:

hl7_transform --help

You can also build your own projects or experiment in Jupyter notebooks by importing the library in your Python code:

from hl7_transform.mapping import HL7Mapping
from hl7_transform.transform import HL7Transform
from hl7_transform.message import HL7Message

mapping = HL7Mapping.from_json('hl7_transform/test/test_transform.json')
message = HL7Message.from_file('hl7_transform/test/test_msg.hl7')
transform = HL7Transform(mapping)
transformed_message = transform(message)

Features

  • read an HL7 message from file, transform it and write it to a new file

Contribute

This project strives from contribution, you are very welcome to extend functionality and make pull request. The easiest ways to contribute are:

If you are having issues, please let us know.

Documentation

Mapping rules

Messages can be transformed using a mapping scheme. This page describes how such a mapping scheme is constructed.

An HL7 message consists of a list of segments, each of them in turn containing fields. The mapping scheme defines how fields of the given message have to be transformed.

If we take an example message:

MSH|^~\&|Doctolib||Doctolib||20200522153917||SIU^S12|d051c31adcc460b5289f|P|2.5.1|||||FRA|UTF-8
SCH||8678012^Doctolib||||neu_pat^Neupatient|||||^^20^202005201615|||||111683^Jackson^Heights||||Doctolib|||||Booked
NTE|||Some notes
PID|||19619205^^^Doctolib^PI||Test^Otto^^^^^L||19900101|M|Geburtsname^^^^^^M||Wilhelmstrasse 118^^Berlin^^11111||+491738599814^^^jackson.heights@doctolib.com~+49301234567
RGS|1
AIG|1|||allg_chir^Allg. Chirurgie

and an example mapping scheme in JSON format:

[
  {
      "target_field": "TQ1.7",
      "operation": "copy_value",
      "source_field": "SCH.11.4"
  }
]

Then the resulting message will contain all fields of the source message, plus a new TQ1 segment with the value from field SCH.11.4 copied into field TQ1.7:

MSH|^~\&|Doctolib||Doctolib||20200522153917||SIU^S12|d051c31adcc460b5289f|P|2.5.1|||||FRA|UTF-8
SCH||8678012^Doctolib||||neu_pat^Neupatient|||||^^20^202005201615|||||111683^Jackson^Heights||||Doctolib|||||Booked
NTE|||Some notes
PID|||19619205^^^Doctolib^PI||Test^Otto^^^^^L||19900101|M|Geburtsname^^^^^^M||Wilhelmstrasse 118^^Berlin^^11111||+491738599814^^^jackson.heights@doctolib.com~+49301234567
RGS|1
AIG|1|||allg_chir^Allg. Chirurgie
TQ1|||||||202005201615

Mapping scheme file

A mapping scheme can be represented either in JSON or in CSV format. CSV format does not support all operations.

JSON-formatted mapping scheme file

An example JSON mapping scheme:

[
  {"target_field": "PID.3", "operation": "set_value", "args": {"value": "123^PatID"}},
  {"target_field": "PV1.2", "operation": "copy_value", "source_field": "PID.18"},
  {"target_field": "PV1.10", "operation": "set_value", "args": {"value": "1922"}}
]
CSV-formatted mapping scheme file

An example CSV mapping scheme is an equivalent to the JSON mapping scheme above:

target_field operation source_field args.value
PID.3 set_value   123^PatID
PV1.2 copy_value PID.18  
PV1.10 set_value 1922  

Operations

A mapping scheme consists of a list of operations, e.g.:

[
  {
    "target_field": "MSH.9.2",
    "operation": "set_value",
    "args": {"value": "S12"}
  },
  {
    "target_field": "MSH.9.3",
    "operation": "set_value",
    "args": {"value": "SIU_S12"}
  }
]

This mapping consists of two operations, both of type “set_value”. The full list of supported operations can be found in List of supported operations.

Every operation consists of a number of mandatory fields: “target_field”, “operation” and “args”.

target_field defines the field where the value shall be written into operation define the operation type (e.g. copy, add etc.) args is a dictionary of optional arguments that depend on the operation.

List of supported operations

A list of operations.

class hl7_transform.operations.AddValues(source_fields, args)

Sums up a list of field values to one value using type conversion as given by args.type.

Example usage in a mapping scheme:

[
    {
        "target_field": "TQ1.8",
        "operation": "add_values",
        "source_fields": ["SCH.11.4", "SCH.11.3"],
        "args": {"type": "int"}
    }
]
class hl7_transform.operations.Concatenate(source_fields, args)

Concatenates two field values as strings placing a separator in between.

Example usage in a mapping scheme:

[
    {
        "target_field": "SCH.9",
        "operation": "concatenate_values",
        "source_fields": ["SCH.11.4", "SCH.11.3"],
        "args": {"separator": " + "}
    }
]
class hl7_transform.operations.CopyValue(source_fields, args)

Copies a value from one field to the other.

Example usage in a mapping scheme:

[
    {
        "target_field": "TQ1.9",
        "operation": "copy_value",
        "source_field": "SCH.11.3"
    }
]
class hl7_transform.operations.GenerateAplhanumericID(source_fields, args)

Generates an alphanumeric ID, producing a random string encoded in the hexadecimal system of length 32 bytes. This is useful for creating random message identifiers.

Example usage in a mapping scheme:

[
    {
        "target_field": "MSH.10",
        "operation": "generate_alphanumeric_id"
    }
]
class hl7_transform.operations.GenerateCurrentDatetime(source_fields, args)

Generates current datetime as a string in HL7 format. This is useful for creating event timestamps.

Example usage in a mapping scheme:

[
    {
        "target_field": "ORC.9",
        "operation": "generate_current_datetime"
    }
]
class hl7_transform.operations.GenerateNumericID(source_fields, args)

Generates an numeric ID, producing a random string encoded with digits in decimal system of length 9 digits. This is useful for creating random patient or event identifiers.

Example usage in a mapping scheme:

[
    {
        "target_field": "PID.3.1",
        "operation": "generate_numeric_id"
    }
]
class hl7_transform.operations.HL7Operation(source_fields, args)

An Operation interface, all operations must derive from this class.

static from_name(name, *args)

Creates the proper operation class instance by name.

Parameters:name –

The name of the operation. Currently available operations are:
class hl7_transform.operations.SetEndTime(source_fields, args)

Computes end time based on start time and duration.

Example usage in a mapping scheme:

[
    {
        "target_field": "SCH.9",
        "operation": "set_end_time",
        "source_fields": ["SCH.11.4", "SCH.11.3"]
    }
]
class hl7_transform.operations.SetValue(source_fields, args)

Sets a field to a given value.

Example usage in a mapping scheme:

[
    {
        "target_field": "ORC.7.6",
        "operation": "set_value",
        "args": {"value": "6"}
    }
]

Message representation

This file contains a wrapper for an HL7 message with convenience functions.

class hl7_transform.message.HL7Message(hl7_message)

Encapsulates an HL7 message.

static from_file(path)

Initialize a message from a file.

static from_string(txt)

Initialize a message from string.

to_string()

Returns a string representation of the encapsulated HL7 message.

Message transformation

This file contains the transformation class.

class hl7_transform.transform.HL7Transform(mapping)

The transformation class that applies an HL7Mapping to an HL7Message.

License

The project is licensed under the MIT license.