Kodjin Data Mapper

Data Mapper is a part of Kodjin interoperability suite. It is a service that implements data conversion from proprietary and legacy formats to FHIR format. Currently, it supports four types of conversions: JSON to FHIR, HL7v2 to FHIR, C-CDA to FHIR and FHIR STU3 to R4.

Endpoints

• POST [fhir_base]/$convert-data

• GET, POST, PUT, DELETE [fhir_base]/templates/[id]

Query parameters

Overview

• Data mapper is implemented using Liquid template engine.
• there're CRUD operations on templates and the ability to store the templates in GitHub repo similarly to the FHIR profiles.

The example of the template

{
        "resourceType": "Patient",
        "id": "{{ PatientId | to_json_string | generate_uuid }}",
        "identifier": [
            {
                "use": "usual",
                "type": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                            "code": "MR"
                        }
                    ]
                },
                "system": "urn:oid:2.16.840.1.113883.19.5",
                "value": "{{ MRN }}"
            }
        ],
        "active": true,
        "name": [
            {
                "family": "{{ LastName }}",
                "given": [
                    "{{ FirstName }}"
                ]
            }
        ],
        "gender": {% if Gender == 'M' -%}
            "male",
        {% elsif Gender == 'F' -%}
            "female",
        {% elsif Gender == 'U' -%}
            "unknown",
        {% elsif code -%}
            "other",
        {% else %}
            "",
        {% endif -%}
        "birthDate": "{{ DOB | add_hyphens_date }}",
        "managingOrganization": {
            "reference": "Organization/2.16.840.1.113883.19.5",
            "display": "Good Health Clinic"
        }
}

Filters

By default, Liquid provides a set of standard filters to assist template creation. Besides these filters, Kodjin Data Mapper also provides some other filters that are useful in conversion, which are listed below.

Hl7v2 specific filters

C-CDA specific filters

String Filters

Math filters

DateTime filters

Collection filters

Miscellaneous filters

Tags

By default, Liquid provides a set of standard tags to assist in template creation. Besides these tags, FHIR Converter also provides some other tags useful in conversion, which are listed below. If these tags do not meet your needs, you can write your own tags.

Data-Mapper API

Create a new template

To upload a new template for Kodjin data-mapper through the API, use a POST request to the [fhir_base]/templates/[template_name] endpoint. Where:

• fhir_base - the base url of Kodjin FHIR Server
• template_name - a name for identifying the template
• templates - is a configurable path in Kodjin data-mapper configuration (template used by default Kodjin configuration)

The request body should contain a JSON object with two parameters:

• type - possible values include: json, html, etc
• payload - the template code

    {
        "type": "json",
        "payload": "Liquid Template Text"
    }

curl --location --request PUT 'https://demo.kodjin.com/templates/example-patient' \
--header 'content-type: application/json' \
--data '{
    "type": "json",
    "payload": "{
        "resourceType": "Patient",
    "id": "{{ msg.PatientId | to_json_string | generate_uuid }}",
    "identifier": [
        {
            "use": "usual",
            "type": {
                "coding": [
                    {
                        "system": "http:
                        "code": "MR"
                    }
                ]
            },
            "system": "urn:oid:2.16.840.1.113883.19.5",
            "value": "{{ msg.MRN }}"
        }
    ],
    "active": true,
    "name": [
        {
            "family": "{{ msg.LastName }}",
            "given": [
                "{{ msg.FirstName }}"
            ]
        }
    ],
    "telecom": [
        {% comment -%} 
            use "[]" to access value if the key contains spaces or other special characters 
        {% endcomment -%}
        {% for p in msg["Phone Number"] -%}
            {
                "system": "phone",
                "value": "{{ p }}",
            },
        {% endfor -%}
    ],
    "gender":   {% if msg.Gender == '\''M'\'' -%}
            "male",
                {% elsif msg.Gender == '\''F'\'' -%}
            "female",
                {% elsif msg.Gender == '\''U'\'' -%}
            "unknown",
                {% elsif code -%}
            "other",
                {% else %}
            "",
                {% endif -%}
    "birthDate": "{{ msg.DOB | add_hyphens_date }}",
    "managingOrganization": {
        "reference": "Organization/2.16.840.1.113883.19.5",
        "display": "Good Health Clinic"
    }
}"
}'

Update a template

To update an existing template for Kodjin data-mapper through the API, use a PUT request to the [fhir_base]/templates/[template_name] endpoint. Where:

• fhir_base - the base url of Kodjin FHIR Server
• template_name - a name for identifying the template

The request body should contains an updated template.

Get a template by id

To retrieve a template, send a GET request with the template name that was used to create the template.

curl --location 'https://demo.kodjin.com/templates/example-patient'

Delete a template

To delete a template send a DELETE request with the template name that was used to create the template.

curl --location --request DELETE 'https://demo.kodjin.com/templates/ADT_X10'

JSON post processing

When a json-type template is rendered or inbound data is transformed using a json-type template, the Data-mapper will apply post-processing to the rendered object. This includes:

• Removing trailing commas
• Removing empty objects
• Removing empty lines
• Removing repeated objects with the same attributes.

Security

Data-mapper is secured with Role-Based Access Control (RBAC). RBAC scopes follow the SMART on FHIR style. When RBAC is enabled in the Kodjin FHIR Server, the following scopes are needed to work with the Data-mapper:

• user/Datamapper.read
• user/Datamapper.write