Skip to content

Developer Guides

Laboratory Workflows

Tutorial: Lab Order Communication between OpenMRS and OpenELIS

In this tutorial, we will use the resources from this documentation - with support from the Laboratory Workflow Implementation Guide and OpenHIE Architecture Specifications - to determine create a pilot implementation of Lab Test Order and Result Communication between an Electronic Medical Record (EMR) and a Lab Information System. We will use validated open-source solutions for each component of our pilot setup, and will use the OpenHIE specifications to guide our approach, the selection and roles of different components, and the language we use for disucssing the various concepts.

To get a better idea about the concepts and data elements were using, visit the Laboratory Workflows IG to a look at: 1. Our list of key concepts 2. Our logical model

We will focus on the following target architecture for our setup, which you can check out in the IG:

hie-overview

This architecture is based on the OpenHIE Specifications for Health Information Exchange components. For this tutorial, we will focus on using OpenMRS the reference implementation of an OpenHIE EMR, and OpenELIS, the reference implementation of an OpenHIE LIS.

Data Model

Task

more info

The Task resource is created along with the corresponding ServiceRequest resource when a clinician creates a TestOrder and decides to send it to OpenELIS.

This resource is used to track the status of the lab order request from initiation to completion, and as a container for all other resources related to the given order.

Example Task:

{
    "resourceType": "Task",
    "id": "88ffa7fb-0419-4097-8b45-24f0d843c5ea",
    "identifier": [
        {
            "system": "http://isanteplus.org/ext/task/identifier",
            "value": "88ffa7fb-0419-4097-8b45-24f0d843c5ea"
        }
    ],
    "basedOn": [
        {
            "reference": "ServiceRequest/ebf83ba0-9d3c-497f-9aa0-d839ec506202",
            "type": "ServiceRequest"
        },
        {
            "reference": "ServiceRequest/73e96ecb-a78d-41c8-a55f-d9b90f759e5f",
            "type": "ServiceRequest"
        }
    ],
    "status": "requested",
    "intent": "order",
    "for": {
        "reference": "Patient/e14e9bda-d273-4c74-8509-5732a4ebaf19",
        "type": "Patient"
    },
    "encounter": {
        "reference": "Encounter/7f5aabd9-6375-47c8-a8d6-30f219b6e2f1",
        "type": "Encounter"
    },
    "authoredOn": "2020-04-28T17:33:19+00:00",
    "owner": {
        "reference": "Practitioner/f9badd80-ab76-11e2-9e96-0800200c9a66",
        "type": "Practitioner"
    }
}

ServiceRequest

more info

The ServiceRequest resource represents the TestOrder placed in OpenMRS. It is referenced from the Task with the Task.basedOn element, and sent to OpenELIS with the Task to initiate the processing of the order.

Example Service Request:

{
    "resourceType": "ServiceRequest",
    "id": "73e96ecb-a78d-41c8-a55f-d9b90f759e5f",
    "status": "active",
    "intent": "order",
    "code": {
        "coding": [
            {
                "code": "790AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
            },
            {
                "system": "http://loinc.org",
                "code": "14682-9"
            },
            {
                "system": "urn:oid:2.16.840.1.113883.3.7201",
                "code": "790"
            }
        ]
    },
    "subject": {
        "reference": "Patient/e14e9bda-d273-4c74-8509-5732a4ebaf19",
        "type": "Patient"
    },
    "encounter": {
        "reference": "Encounter/7f5aabd9-6375-47c8-a8d6-30f219b6e2f1",
        "type": "Encounter"
    }
}

DiagnosticReport

more info

The DiagnosticReport resource is the container for the results of an Order, and holds these results in the DiagnosticReport.result element as references to Observation resources.

Example Diagnostic Report

{
  "resourceType": "DiagnosticReport",
  "id": "93",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2020-04-28T17:33:36.163+00:00",
    "source": "#55t4lpDZF4q3TCZ0"
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\"> Untitled Diagnostic Report </div><table class=\"hapiPropertyTable\"><tbody><tr><td>Status</td><td>FINAL</td></tr></tbody></table></div>"
  },
  "identifier": [
    {
      "system": "https://isanteplusdemo.com/openmrs/ws/fhir2/",
      "value": "ebf83ba0-9d3c-497f-9aa0-d839ec506202"
    }
  ],
  "status": "final",
  "code": {
    "coding": [
      {
        "code": "1008AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      },
      {
        "system": "http://loinc.org",
        "code": "22748-8"
      },
      {
        "system": "urn:oid:2.16.840.1.113883.3.7201",
        "code": "1008"
      }
    ]
  },
  "subject": {
    "reference": "Patient/2"
  },
  "result": [
    {
      "reference": "Observation/92",
      "type": "Observation"
    }
  ]
}

Observation

more info

The Observation resource contains the results of the Lab Order request.

Example Observation:

{
  "resourceType": "Observation",
  "id": "92",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2020-04-28T17:33:36.124+00:00",
    "source": "#xAVz0uUE6c3l42Za"
  },
  "identifier": [
    {
      "system": "https://isanteplusdemo.com/openmrs/ws/fhir2/",
      "value": "ebf83ba0-9d3c-497f-9aa0-d839ec506202"
    }
  ],
  "status": "final",
  "code": {
    "coding": [
      {
        "code": "1008AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      },
      {
        "system": "http://loinc.org",
        "code": "22748-8"
      },
      {
        "system": "urn:oid:2.16.840.1.113883.3.7201",
        "code": "1008"
      }
    ]
  },
  "subject": {
    "reference": "Patient/2"
  },
  "valueQuantity": {
    "value": 55,
    "unit": "UI/L"
  }
}

Patient

more info

The Patient resource contains vital information for OpenELIS to fullfill the lab order request, and is referenced by the Task.

Example Patient:

{
    "resourceType": "Patient",
    "id": "e14e9bda-d273-4c74-8509-5732a4ebaf19",
    "identifier": [
        {
            "id": "5981a256-d60c-44b1-beae-9bdd2cf572f8",
            "use": "official",
            "system": "iSantePlus ID",
            "value": "10012R"
        },
        {
            "id": "75a67d54-6fff-44d1-9c3e-2116c967b475",
            "use": "usual",
            "system": "Code National",
            "value": "100000"
        },
        {
            "id": "29447d21-3cd6-42a9-9ab2-79ebfa710a01",
            "use": "usual",
            "system": "ECID",
            "value": "04d759e0-5d02-11e8-b899-0242ac12000b"
        }
    ],
    "active": true,
    "name": [
        {
            "id": "511275de-e301-44a3-95d2-28d0d3b35387",
            "family": "Mankowski",
            "given": [
                "Piotr"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1987-01-01",
    "deceasedBoolean": false,
    "address": [
        {
            "id": "d4f7c809-3d01-4032-b64d-4c22e8eccbbc",
            "use": "home",
            "country": "Haiti"
        }
    ]
}

Relevant FHIR Docs * Using Tasks in a RESTful Context * Workflow Module * Diagnostic Module * Example: Workflow states for a lab order for a blood test * Option G: POST of Task to fulfiller's system

Relevant OpenMRS Talk Posts The handling and mapping of lab order status for the lab workflow

Openmrs 3.x

  1. Setup OpenRMS 3.x on top an instance of the Reference Application click here for more infromation

  2. Install the Following Modules

  3. Configure the required settings

    • labonfhir.openElisUrl ,The URL for the FHIR server where OpenELIS polls the Orders From.
    • labonfhir.openElisUserUuid ,UUID for the service user that represents OpenELIS
      see more on Configuring the above Modules.
      Note: The Lab test Concept should be of class Test ,and should be mapped to a Loinc code that matches a the Test Loinc Code in OpenELIS

  4. Go to the Reff App (2.x) Patient Dashbord Prescribed Medication Widget. screen1
    see more on Creating Orders using the Order Entry Owa. screen1

    If the Lab on FHIR module is rightly configured ,it will generate the lab FHIR Bundle and push to the remote Fhir Server for OpenELIS to poll the orders

  5. Start up the OpenELIS Update Task In order to be able to poll OpenELIS for available results, we need to turn on the following task in the OpenMRS scheduler: System Administration → Advanced Administration → Scheduler → Manage Scheduler screen1

  6. Enable the patient-test-results-app for the 3.x Frontenx. Go to the Patient DashBoard in 3.x ui and click Test Results. screen1

iSantéPlus

  1. Install iSantePlus using one of these approaches.

  2. Install the Following Modules

  3. Configure the required settings .

    • labonfhir.openElisUrl ,The URL for the FHIR server where OpenELIS polls the Orders From.
    • labonfhir.openElisUserUuid ,UUID for the service user that represents OpenELIS

    see more on Configuring the Lab On FHIR Modules.

  4. To place Lab Orders ,Fill the Laboratory Analysis Form , select OPenELIS as destination Lab and Save.
    Find Patient → Patient DashBord → Forms → Laboratory Analysis screen1 screen1 screen1 NB. The Patient Must have an active vist

  5. Start up the OpenELIS Update Task in order to poll for Completed Results from OpenELIS
    System Administration → Advanced Administration → Scheduler → Manage Scheduler screen1

  6. To View The results ,Go to Laboratory History on the Patient DashBoard under General Actions.
    Find Patient → Patient DashBord → Laboratory History screen1 screen1

OpenELIS Global 2.6.x

The FHIR based Lab Workflow is supported in OpenELIS 2.6 .

  1. Start an instance of OpenELIS with the following configuration properties set in the properties file.

    • org.openelisglobal.fhirstore.uri=<localFhirServerUrl> . This is the Fhir Server that runs paralel with OPenELIS

    • org.openelisglobal.remote.source.uri=<remoreFhirServerUr>. This is the Fhir server that the Lab on FHIR module points to ie via the labonfhir.openElisUrl

    • org.openelisglobal.remote.source.updateStatus=true
    • org.openelisglobal.remote.source.identifier=Practitioner/<userUuuid> .This is the UUID of the user who created the Order ie labonfhir.openElisUserUuid

    • org.openelisglobal.task.useBasedOn=true

    • org.openelisglobal.fhir.subscriber=h<remoreFhirServerUrl> .

    • org.openelisglobal.fhir.subscriber.resources=Task,Patient,ServiceRequest,DiagnosticReport,Observation,Specimen,Practitioner,Encounter

  2. Ensure OpenELIS has the test that maps to the same LOINC code as the test Concept in OpenMRS. This can be added via the
    Admin page → Test Management → Add Tests screen1

  3. Configure OpenELIS to accept electronic orders.
    Admin → Order Entry Configuration → external orders screen1

  4. Search for the Electronic Orders ie Order → Electronic Orders and then Complete the Order Note that the user should have the right Lab Unit Priviledges to complete the Order screen1

  5. After Results are captured and Validated , OpenELIS sends back the results to OpenMRS as a Diagnostic Report with an Observation

Instant OpenHIE V2

Packaging Hie Implementations

References:

Steps:

1. Add scripts for downloading Instant OpenHIE V2 CLI and add utilities.

https://github.com/jembi/platform/blob/main/get-cli.sh https://github.com/jembi/platform/tree/main/utils

2. Add Dockerfile in root directory of the project that inherits from Instant OpenHIE Parent Docker Image

https://github.com/jembi/platform/blob/main/Dockerfile

3. Download CLI

./get-cli.sh

4. Build and publish Docker image

4.1. Build Local Docker image
4.2. Publish Docker image
4.3. Update config.yml file

5. Add HIE components

Country-specific Dev Guides

Dev Guide: Botsawana Laborabory Workflows

Introduction

This guide will go over development, configuration, and debugging the laboratory workflow for Botswana. This workflow includes functionality in the SHR and Fhir Converter projects, linked below:

The functionality includes Kafka-managed workflows in the SHR project, and FHIR --> HL7 and HL7 --> FHIR mappings in the Fhir Converter project.

Prerequesites

Before getting started, make sure you complete the following prerequisites:

1. Connect to the Botswana VPN

See the relevant emails and slack messages for instructions.

2. Add the following ssh config to your ~/.ssh/config file:
Host hie-pilot.gov.bw
  HostName 10.0.10.111
  User hie
3. Connect to the HIE server using remote VS Code

See slack for the password.

4. Set up the relevant VS Code projects by opening the following folders:
$ cd /u01/code/shared-health-record
$ code .

$ cd /u01/code/openhim-mediator-fhir-converter
$ code .

$ cd /home/hie/hie-botswana
$ code .

The first two are used for development of the SHR and the FHIR Converter, respectively. The third is the main project for running the HIE. We run all the other containers EXCEPT FOR the shr and fhir-converter containers from that project.

5. Add remote debugging configurations to the SHR and FHIR Converter projects

Add the following configurations to the .vscode/launch.json files in the SHR and FHIR Converter projects:

You can open the file by clicking the debug icon on the left side of the VS Code window, then clicking the gear icon next to the "Run and Debug" dropdown, then clicking "Open launch.json".

5.1. SHR
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Docker: Attach to Node",
            "type": "node",
            "request": "attach",
            "restart": true,
            "port": 9229,
            "address": "localhost",
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/app",
            "protocol": "inspector",
            "sourceMaps": true
        },
    ]
}
5.2 FHIR Converter
{
    "version": "0.2.0",
    "configurations": [

        {
            "name": "Docker: Attach to Node",
            "type": "node",
            "request": "attach",
            "restart": true,
            "port": 9230,
            "address": "localhost",
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/app",
            "protocol": "inspector",
            "sourceMaps": true
        },
    ]
}
6. Forward the following ports in VS Code for the SHR and FHIR Converter projects:
  • SHR: 9229
  • FHIR Converter: 9230

Useful Docker Commands

1. Show logs of shr, shr-fhir, and fhir-converter containers
docker logs -f -n 100 shr
docker logs -f -n 100 shr-fhir
docker logs -f -n 100 built-fhir-converter
2. Rebuild and run SHR or FHIR Converter containers
cd <respective project directory>
docker-compose -f debug.docker-compose.yml up --build -d
3. Rebuild and Reset the FHIR Converter templates after making changes

The templates are stored in a volume, so you need to remove the volume and rebuild the container to update any changes made to the templates.

cd /u01/code/openhim-mediator-fhir-converter
docker-compose -f debug.docker-compose.yml down -v
docker-compose -f debug.docker-compose.yml up --build -d

Overview of project structure and code locations

1. SHR

The SHR project contains two main that has all of the Botswana-specific workflows. One focuses on FHIR-based workflows, and the other manages the incoming HL7 messages.

The FHIR-based workflows for Botswana are located in src/workflows/labWorkflowsBw.ts: https://github.com/I-TECH-UW/shared-health-record/blob/pmanko-lab-workflow-updates/src/workflows/labWorkflowsBw.ts.

The HL7-based workflows are located in src/workflows/hl7WorkflowsBw.ts: https://github.com/I-TECH-UW/shared-health-record/blob/pmanko-lab-workflow-updates/src/workflows/hl7WorkflowsBw.ts

The workflows are organized using Kafka topics and picked up by Kafka workers.

2. FHIR Converter

The FHIR Converter project contains the mappings from FHIR to HL7 and HL7 to FHIR. The mappings are located in the data/templates directory: https://github.com/I-TECH-UW/openhim-mediator-fhir-converter/tree/pmanko-server-update/data/templates

The relevant templates are ADT_A04_TO_IPMS.hbs and ORM_O01_TO_IPMS.hbs in the fhir subdirectory and ADT_A04_FROM_IPMS.hbs and ORU_R01_FROM_IPMS.hbs in the hl7 subdirectory.

2.1. HL7 to FHIR

For the HL7-->FHIR templates in the data/templates/hl7 directory, there are nested handlebar template files that provide variable replacement for references to the HL7 message field names.

2.2. FHIR to HL7

For the FHIR-->HL7 templates in the data/templates/fhir directory, the variable replacement is done using custom mappings defined in the parseAdt() and parseOrm() functions in the /src/lib/fhir/fhir.js file: https://github.com/I-TECH-UW/openhim-mediator-fhir-converter/blob/e1f8085258b95735559c69d5f36eaf5ff0fd272b/src/lib/fhir/fhir.js#L107. The correct variables need to be added to the res object, and are then available as variables in the handlebar templates.

Turning on Remote Debugging for the projects:

Make sure that the docker-compose entries in the debug.docker-compose.yml files for the SHR and FHIR Converter projects have debugging turned on for their respective projects.

The Fhir Converter project should have the following entrypoint entry:

  entrypoint: /app/deploy/debug.sh

The SHR project should have the following entrypoint entry:

  entrypoint: node --inspect=0.0.0.0:9230 /app/dist/app.js

Make sure that you have the Remote Debugging setup as outlined in the Prerequisites section of this guide.

Make sure that you have the relevant ports forwarded in VS Code for the SHR and FHIR Converter projects.

Finally, make sure that you run yarn build on the project you want to debug, and also that you ran docker-compose -f debug.docker-compose.yml up --build -d after making any changes to the code to see them reflected in the running container.

Postman Overview

The Postman collection for the Botswana HIE Lab Workflows is located here: https://www.postman.com/itechuw/workspace/botswana-hie/collection/1525496-8be9c19c-9e7b-4316-adea-3604884af5d7?action=share&creator=1525496

For IPMS testing, we focus on the following folder: https://www.postman.com/itechuw/workspace/botswana-hie/folder/1525496-0c135557-d6a8-4928-a649-2546a18d075f?ctx=documentation

We also use the hie-pilot.gov.bw environment.

The Add Draft Order Bundle request sends a draft order that does result in concept and location mappings, but does not send an HL7 message to IPMS. It also generates new patient data as outlined in the Pre-request Script tab.

The Add Requested Order Bundle request sends a requested order that does concept and location mappings, and also sends an HL7 message to IPMS. It uses the data generated by the Add Draft Order Bundle request, and can be re-run multiple times with the same patient information.

OpenHIE Testing

For quickly testing changes to the Fhir Converter templates, you can re-run the converter request from OpenHIE, which can be accessed here:

https://hie-pilot.gov.bw/

This page loads slowly as it tries to pull external resources that are not available on the network.

Dev Guide: Patient Identity Management Workflow in Cote d'Ivoire

This guide will go over development, configuration, and debugging the laboratory workflow for Botswana. This workflow includes functionality in the SHR and Fhir Converter projects, linked below:

The functionality includes Kafka-managed workflows in the SHR project, and FHIR --> HL7 and HL7 --> FHIR mappings in the Fhir Converter project.

Demo Videos