Connect Jembi HEARTH FHIR Server (1.1)

Overview

Jembi HEARTH FHIR Server can be retrieved from https://github.com/jembi/hearth.

For Jembi HEARTH FHIR Server subscriptions are simulated at the moment. When polling the whole created and updated data for a specific time frame must be retrieved from the FHIR Server since neither sorting by last updated timestamp (required for paging without gaps) nor retrieval of single elements is supported currently.

Setup of DHIS2 FHIR Adapter

The DHIS2 FHIR Adapter receives regular notifications from an external job that instructs the Adapter to poll for created or updated FHIR resources on the FHIR server.

Import must have been enabled in the configuration file of the DHIS2 FHIR Adapter. The snippet below contains the relevant settings.

spring:
  # Settings of the Artemis message queueing system. For a non-clustered
  # installation the embedded client can be used where the data is stored
  # on the local file system.
  artemis:
    # Settings for the embedded client, that can be used for a non-clustered
    # installation.
    embedded:
      # Specifies of the embedded client should be enabled. If the adapter
      # runs in a clustered environment the embedded client must not be enabled
      # and host, port, username and password for the Artemis broker must be
      # specified.
      enabled: true

management:
  health:
    jms:
      # JMS health check can be enabled when Artemis queue is available.
      enabled: false

dhis2.fhir-adapter:
  # Specifies if the automatic import of FHIR resources to DHIS2 is enabled.
  import-enabled: true

Important Note: Before doing this configuration the initial setup for the mapping of the FHIR Patient to the DHIS 2 Tracked Entity Type Person should have been completed.

Register Identifier Systems

Register Patient Identifier System

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/systems/ff842c76-a529-4563-972d-216b887a3573 -d '{
  "name": "Sierra Leone Patient ID",
  "code": "SL_PATIENT_ID",
  "systemUri": "http://example.sl/patients",
  "fhirDisplayName": "Sierra Leone Patient ID"
}'

Register Organization Identifier System

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3 -d '{
  "name": "Sierra Leone Organization ID",
  "code": "SL_ORGANIZATION_ID",
  "systemUri": "http://example.sl/organizations",
  "fhirDisplayName": "Sierra Leone Organization ID"
}'

Register Location Identifier System

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/systems/2dd51309-3319-40d2-9a1f-be2a102df4a7 -d '{
  "name": "Sierra Leone Location ID",
  "code": "SL_LOCATION_ID",
  "systemUri": "http://example.sl/locations",
  "fhirDisplayName": "Sierra Leone Location ID"
}'

FHIR Client for FHIR Server

Create FHIR Client

The FHIR Endpoint contains no authorization header for the FHIR Server. This can be configured as needed. The adapter endpoint contains the authorization header that must be sent when polling for the created and updated FHIR resources.

The encoding of username and password to a basic authorization header can be done for example on the following web site (no security critical data should be entered there): https://www.blitter.se/utils/basic-authentication-header-generator/

It is important that JSON format is used to communicate with Jembi HEARTH FHIR Server and requests to the FHIR Server do not use any sorting. This can be specified when creating the FHIR client as show below.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f -d '{
  "name": "FHIR Server",
  "code": "FHIR_SERVER",
  "description": "Jembi HEARTH FHIR Server.",
  "fhirVersion": "DSTU3",
  "dhisEndpoint": {
    "authenticationMethod": "BASIC",
    "username": "admin",
    "password": "district"
  },
  "fhirEndpoint": {
    "baseUrl": "http://localhost:3447/fhir",
    "useRemote": true,
    "useJsonFormat": true,
    "sortSupported": false
  },
  "adapterEndpoint": {
    "baseUrl": "http://localhost:8081",
    "authorizationHeader": "Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs",
    "subscriptionType": "REST_HOOK"
  }
}'

Create FHIR Client Resources

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClientResources/667bfa41-867c-4796-86b6-eb9f9ed4dc94 -d '{
  "fhirResourceType": "PATIENT",
  "fhirClient": "http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f"
}'

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClientResources/b32b4098-f8e1-426a-8dad-c5c4d8e0fab6 -d '{
  "fhirResourceType": "OBSERVATION",
  "fhirClient": "http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f"
}'

Create FHIR Client Systems

curl -XPOST -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClientSystems -d '{
  "fhirResourceType": "ORGANIZATION",
  "fhirClient": "http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f",
  "system": "http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3"
}'

curl -XPOST -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClientSystems -d '{
  "fhirResourceType": "LOCATION",
  "fhirClient": "http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f",
  "system": "http://localhost:8081/api/systems/2dd51309-3319-40d2-9a1f-be2a102df4a7"
}'

curl -XPOST -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/fhirClientSystems -d '{
  "fhirResourceType": "PATIENT",
  "fhirClient": "http://localhost:8081/api/fhirClients/73cd99c5-0ca8-42ad-a53b-1891fccce08f",
  "system": "http://localhost:8081/api/systems/ff842c76-a529-4563-972d-216b887a3573"
}'

Setup of Jembi HEARTH FHIR Server

The FHIR Server must use the FHIR version as specified when creating the FHIR client of the Adapter. How to specify FHIR version DSTU3 is described https://github.com/jembi/hearth.

The FHIR Server must use the same time zone like the DHIS2 FHIR Adapter. Otherwise filtering based on last updated timestamp will not work.

Setup of FHIR Subscriptions

For each FHIR client resource that has been configured on the Adapter a corresponding external job (e.g. UNIX cron job) that notifies the Adapter about possible created or updated FHIR resources must be created. The last parts of the Adapter endpoint URL of the FHIR subscription must be the ID of the FHIR client followed by the ID of the FHIR client resource. Since the setup above contains two FHIR client resources, two notification URLs can be requested. The headers must contain the authorization header that is defined in the corresponding FHIR client configuration of the Adapter.

• FHIR Patient: curl -XPOST -i -H 'Authorization: Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs' http://localhost:8081/remote-fhir-rest-hook/73cd99c5-0ca8-42ad-a53b-1891fccce08f/667bfa41-867c-4796-86b6-eb9f9ed4dc94
• FHIR Observation: curl -XPOST -i -H 'Authorization: Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs' http://localhost:8081/remote-fhir-rest-hook/73cd99c5-0ca8-42ad-a53b-1891fccce08f/b32b4098-f8e1-426a-8dad-c5c4d8e0fab6

Such an operation could also be implemented as a hook in HEARTH.

Verification of Setup

Create FHIR Organization for Connaught Hospital in Sierra Leone demo database.

curl -XPOST -i -H "Content-Type: application/fhir+json" http://localhost:3447/fhir/Organization -d \
  '{
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "http://example.sl/organizations",
        "value": "OU_278320"
      }
    ],
    "name": "Connaught Hospital"
  }'

The result will return a Location header with a value like Location: /fhir/Organization/e1b4bb6b-0f2f-4abc-9689-60db0c69c40a/_history/2fec93c6-ec1a-41d0-aff5-3baa734e7b3b. The value resulting organization ID (in this case e1b4bb6b-0f2f-4abc-9689-60db0c69c40a) must be entered in the JSON body below.

Create a FHIR Patient that is managed by Connaught Hospital.

curl -XPOST -i -H "Content-Type: application/fhir+json" http://localhost:3447/fhir/Patient -d \
  '{
    "resourceType": "Patient",
    "identifier": [
      {
        "system": "http://example.sl/patients",
        "value": "7383891882"
      }
    ],
    "name": [
      {
        "family": "West",
        "given": [
          "Joe",
          "Alan",
          "Scott"
        ]
      }
    ],
    "gender": "male",
    "birthDate": "2019-02-02",
    "address": [
      {
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/geolocation",
            "extension": [
              {
                "url": "latitude",
                "valueDecimal": 8.4665341
              },
              {
                "url": "longitude",
                "valueDecimal": -13.262743
              }
            ]
          }
        ],
        "line": [
          "Water Road 675",
          "Apartment 62"
        ],
        "city": "Freetown",
        "country": "Sierra Leone"
      }
    ],
    "managingOrganization": {
      "reference": "Organization/e1b4bb6b-0f2f-4abc-9689-60db0c69c40a"
    }
  }'

After creating the two FHIR resources on the FHIR Server and waiting for the external notification, the DHIS 2 Tracked Entity that refers to the FHIR patient above should exist.