Connect HAPI FHIR JPA Server (1.1)

Overview

HAPI FHIR JPA Server supports REST hook subscriptions with and without payloads. Either use HAPI FHIR JPA Server Starter or for versions prior HAPI FHIR 3.6.0 also HAPI FHIR JPA Server Example.

Setup of DHIS2 FHIR Adapter

The DHIS2 FHIR Adapter receives a notification from the HAPI FHIR JPA Server that may include optionally the created or updated FHIR resource. If the created or updated FHIR resource is not included the Adapter may poll for created or updated FHIR resources of the notified FHIR resource type (optionally by a configurable filtered).

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 the basic authentication of the FHIR Server. This example contains username dhis2 and password dhis2_1. The adapter endpoint contains the authorization header that must be sent by the FHIR Server (specified header in FHIR Subscription). If the FHIR Server uses FHIR version R4, the FHIR version below must be changed from DSTU3 to R4.

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/

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": "HAPI FHIR JPA Server.",
  "fhirVersion": "DSTU3",
  "dhisEndpoint": {
    "authenticationMethod": "BASIC",
    "username": "admin",
    "password": "district"
  },
  "fhirEndpoint": {
    "baseUrl": "http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3",
    "useRemote": true,
    "headers": [
      {
        "name": "Authorization",
        "value": "Basic ZGhpczI6ZGhpczJfMQ==",
        "secure": true
      }
    ]
  },
  "adapterEndpoint": {
    "baseUrl": "http://localhost:8081",
    "authorizationHeader": "Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs",
    "subscriptionType": "REST_HOOK_WITH_JSON_PAYLOAD"
  }
}'

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 HAPI FHIR JPA Server

The FHIR Server must use the FHIR version as specified when creating the FHIR client of the Adapter.

Setup of FHIR Subscriptions

For each FHIR client resource that has been configured on the Adapter a corresponding subscription on the FHIR Server can 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 subscriptions can be created on the FHIR Server. The headers must contain the authorization header that is defined in the corresponding FHIR client configuration of the Adapter.

curl -XPOST http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3/Subscription -i -H 'Content-Type: application/json' -d \
  '{
    "resourceType": "Subscription",
    "criteria": "Patient?",
    "channel": {
      "type": "rest-hook",
      "endpoint": "http://localhost:8081/remote-fhir-rest-hook/73cd99c5-0ca8-42ad-a53b-1891fccce08f/667bfa41-867c-4796-86b6-eb9f9ed4dc94",
      "header": "Authorization: Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs",
      "payload": "application/fhir+json"
    }, 
    "status": "requested"
  }'

curl -XPOST http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3/Subscription -i -H 'Content-Type: application/json' -d \
  '{
    "resourceType": "Subscription",
    "criteria": "Observation?",
    "channel": {
      "type": "rest-hook",
      "endpoint": "http://localhost:8081/remote-fhir-rest-hook/73cd99c5-0ca8-42ad-a53b-1891fccce08f/b32b4098-f8e1-426a-8dad-c5c4d8e0fab6",
      "header": "Authorization: Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs",
      "payload": "application/fhir+json"
    }, 
    "status": "requested"
  }'   

Verification of Setup

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

curl -XPUT -i -H "Content-Type: application/fhir+json" http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3/Organization/cf510c0f-8b9e-4ba4-aa6f-82c777a1b0e2 -d \
  '{
    "resourceType": "Organization",
    "id": "cf510c0f-8b9e-4ba4-aa6f-82c777a1b0e2",
    "identifier": [
      {
        "system": "http://example.sl/organizations",
        "value": "OU_278320"
      }
    ],
    "name": "Connaught Hospital"
  }'

Create a FHIR Patient that is managed by Connaught Hospital.

curl -XPOST -i -H "Content-Type: application/fhir+json" http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3/Patient -d \
  '{
    "resourceType": "Patient",
    "identifier": [
      {
        "system": "http://example.sl/patients",
        "value": "1383891882"
      }
    ],
    "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/cf510c0f-8b9e-4ba4-aa6f-82c777a1b0e2"
    }
  }'

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