Skip to content
This repository has been archived by the owner on Jan 21, 2022. It is now read-only.

Tracker Program with Vital Sign (1.1)

Jump to bottom
Volker Schmidt edited this page Mar 21, 2019 · 19 revisions

Overview

This document describes how to configure a Tracker Program with two Program Stages and how to add or adjust a mapping and transformation for data that exists in two Program Stages. The Child Program that is included in Sierra Leone demo database is used for this example.

Setup of the Adapter

The Adapter must be installed with Sierra Leone demo database. The initial setup of the Adapter can be done with the simple setup user interface. The configuration can be made with or without a FHIR Server (FHIR interfaces only). As Tracked Entity setup the setup for Sierra Leone database can be selected.

Rules, Mappings and Transformations

Setup of Tracker Program

Automatic Enrollment into Tracker Program

The Adapter can perform an auto enrollment of a DHIS 2 Tracked Entity Instance into a Tracker Program. If an automatic enrollment is applicable, must be decided by a script. The following steps show how to create the corresponding script.

First the script and its arguments must be created. The script has three arguments. The first argument is the reference to the tracked entity attribute that contains the birth date of the person, the second is the maximum age of the enrolled person and the third argument is the unit of the maximum age.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125 -d '{
  "name" : "Child Programme Creation Applicable",
  "description" : "Checks if the enrollment into child programme is applicable. The enrollment is applicable if the person is younger than a defined amount time.",
  "code" : "CHILD_PROGRAMME_CREATION_APPLICABLE",
  "scriptType" : "EVALUATE",
  "returnType" : "BOOLEAN",
  "variables" : [ "TRACKED_ENTITY_INSTANCE", "DATE_TIME" ]
}'

Create the first argument, which is a reference (can be by ID, CODE or NAME) of the tracked entity attribute that contains the birth date of the person.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptArgs/b06c9036-006b-4043-9c6f-57dd7286098b -d '{
  "name" : "birthDateAttribute",
  "dataType" : "TRACKED_ENTITY_ATTRIBUTE_REF",
  "mandatory" : true,
  "defaultValue" : "CODE:MMD_PER_DOB",
  "description" : "The reference of the tracked entity attribute that contains the birth date of the Person.",
  "script" : "http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125"
}'

Create the second argument, which is the maximum age of the enrolled person.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptArgs/8cddd857-d510-472c-835a-d9454ffe1d39 -d '{
  "name" : "age",
  "dataType" : "INTEGER",
  "mandatory" : true,  
  "defaultValue" : "1",
  "description" : "The person must be younger than the this amount of time (in specified units).",
  "script" : "http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125"
}'

Create the third script argument, which is the unit of the maximum age of the enrolled person.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptArgs/331db7c9-edd8-4ff5-9e77-40c391aa789e -d '{
  "name" : "ageUnit",
  "dataType" : "DATE_UNIT",
  "mandatory" : true,
  "defaultValue" : "YEARS",
  "description" : "The person must be younger than the this amount of time (in specified units).",
  "script" : "http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125"
}'

Create the script source code for FHIR version DSTU3 and R4. The script uses the date time utilities that are provided by the Adapter and calculate if the birth date attribute of the tracked entity instance is younger than the specified age. The calculation is performed relative to the specified dateTime, which is the resulting date of the enrollment (which is in this case the birth date).

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptSources/1f9dc84d-29a5-4460-9192-eb03cea156d9 -d $'{
  "sourceText" : "dateTimeUtils.isYoungerThan(dateTime, trackedEntityInstance.getValue(args[\'birthDateAttribute\']), args[\'age\'], args[\'ageUnit\'])",
  "sourceType" : "JAVASCRIPT",
  "fhirVersions" : [ "DSTU3", "R4" ],
  "script" : "http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125"
}'

Create the executable script for the script above (arguments can be changed for an executable script).

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/executableScripts/dfb7f13c-ae21-4cfb-8815-6f1416ca8388 -d '{
  "name" : "Child Programme Creation Applicable",
  "code" : "CHILD_PROGRAMME_CREATION_APPLICABLE",
  "description" : "Checks if the enrollment of a person is applicable.",
  "script" : "http://localhost:8081/api/scripts/3ddfc83e-0655-46db-8111-0a3370970125"
}'

Tracker Program Initialization

The Child Programme uses the birth date as the incident date. This must be filled from the tracked entity.

First the script and its arguments must be created. The script has one argument, which is the reference to the tracked entity attribute that contains the birth date of the person. The script could also reference the applicable script above as a base script in order to inherit this attribute and its default value from the other script.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scripts/60e83e18-5f66-40a1-9c9d-1d993e5ccdb3 -d '{
  "name" : "Child Programme Creation",
  "description" : "Child programme creation.",
  "code" : "CHILD_PROGRAMME_CREATION",
  "scriptType" : "EVALUATE",
  "returnType" : "BOOLEAN",
  "inputType" : "DHIS_EVENT",
  "variables" : [ "CONTEXT", "ENROLLMENT" ]
}'

Create the first argument, which is a reference (can be by ID, CODE or NAME) of the tracked entity attribute that contains the birth date of the person.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptArgs/363ed415-be4a-4311-a7bf-780a304d6f8c -d '{
  "name" : "birthDateAttribute",
  "dataType" : "TRACKED_ENTITY_ATTRIBUTE_REF",
  "mandatory" : true,
  "defaultValue" : "CODE:MMD_PER_DOB",
  "description" : "The reference of the tracked entity attribute that contains the birth date of the Person.",
  "script" : "http://localhost:8081/api/scripts/60e83e18-5f66-40a1-9c9d-1d993e5ccdb3"
}'

Create the script source code for FHIR version DSTU3 and R4.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/scriptSources/1f9dc84d-29a5-4460-9192-fb73cea156d9 -d $'{
  "sourceText" : "enrollment.setIncidentDate(trackedEntityInstance.getValue(args[\'birthDateAttribute\']))",
  "sourceType" : "JAVASCRIPT",
  "fhirVersions" : [ "DSTU3", "R4" ],
  "script": "http://localhost:8081/api/scripts/60e83e18-5f66-40a1-9c9d-1d993e5ccdb3"
}'

Create the executable script for the script above (arguments can be changed for an executable script).

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/executableScripts/6836cbd1-93ba-4ab8-a4cb-69348ad9d099 -d '{
  "name" : "Child Programme Creation",
  "code" : "CHILD_PROGRAMME_CREATION",
  "description" : "Child programme creation.",
  "script" : "http://localhost:8081/api/scripts/60e83e18-5f66-40a1-9c9d-1d993e5ccdb3"
}'

Tracker Program Definition

The program definition below defines the Child Programme. Automatic enrollment is enabled and as enrollment date the incident date that is calculated by the creation script is used.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/trackerPrograms/45e61665-754d-4861-891e-a2064fc0ae7d -d '{
  "name": "Child Programme",
  "programReference": {
    "value": "Child Programme",
     "type": "NAME"
  },
  "enabled": true,
  "creationEnabled": true,
  "enrollmentDateIsIncident": true,
  "expEnabled": true,
  "fhirCreateEnabled": true,
  "fhirUpdateEnabled": true,
  "fhirDeleteEnabled": true,
  "trackedEntityFhirResourceType": "PATIENT",
  "creationApplicableScript": "http://localhost:8081/api/executableScripts/dfb7f13c-ae21-4cfb-8815-6f1416ca8388",
  "creationScript": "http://localhost:8081/api/executableScripts/6836cbd1-93ba-4ab8-a4cb-69348ad9d099",
  "trackedEntityRule": "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35"
}'

Setup of Tracker Program Stages

The Child Programme has two program stages (events). Each program stage must be configured in the Adapter. If automatic enrollment has been enabled it makes also sense to enable automatic creation of program stage instances (at least of initial program stage).

Create the definition of the first program stage. As date of the event the incident date of the enrollment should be used.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/trackerProgramStages/4c074c85-be49-4b9d-8973-9e16b9615dad -d '{
  "name": "Birth",  
  "programStageReference": {
    "value": "Birth",
    "type": "NAME"
  },
  "enabled": true,
  "creationEnabled": true,  
  "eventDateIsIncident": true,
  "expEnabled": true,
  "fhirCreateEnabled": true,
  "fhirUpdateEnabled": true,
  "fhirDeleteEnabled": true,
  "program": "http://localhost:8081/api/trackerPrograms/45e61665-754d-4861-891e-a2064fc0ae7d"              
}'

Create the definition of the second program stage. Also for this program stage instance the event date should be calculated based on the incident date. The program stage has in DHIS 2 the setting that it should start 6 days after the start. These 6 days are added to the incident date in order to calculate the event date.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/trackerProgramStages/526b4e01-7747-47ef-a25d-f32ccd739e87 -d '{
  "name": "Baby Postnatal",
  "programStageReference": {
    "value": "Baby Postnatal",
    "type": "NAME"
   },                
  "enabled": true,
  "creationEnabled": true,  
  "eventDateIsIncident": true,
  "expEnabled": true,
  "fhirCreateEnabled": true,
  "fhirUpdateEnabled": true,
  "fhirDeleteEnabled": true,
  "program": "http://localhost:8081/api/trackerPrograms/45e61665-754d-4861-891e-a2064fc0ae7d"              
}'

Setup executable Scripts for Body Weight with Unit Grams

By default the standard script that transforms a FHIR Observation that contains a body weight to a data element value uses the unit kilogram to perform the transformations. Since the Child Programme uses grams, the executable script must override the the unit.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/executableScripts/06005c16-cbc8-4a50-abb0-7b16140c109c -d '{
  "name" : "FHIR Body Weight Observation to Gram Data Element",
  "code" : "TRANSFORM_FHIR_TO_GRAM_BODY_WEIGHT",
  "overrideArguments" : [ {
    "overrideValue" : "GRAM",
    "enabled" : true,
    "argument": "http://localhost:8081/api/scriptArgs/3d15bf81-343c-45bc-9c28-1e87a8da6fa5"
  } ],
  "script": "http://localhost:8081/api/scripts/f1da6937-e2fe-47a4-b0f3-8bbff7818ee1"
}'

Setup of FHIR Resource to DHIS 2 Resource Mappings and Transformations

The Child Programme uses the body weight of the child in two program stages. In the first program stage it is used as birth weight and in the second program stage it is used as infant weight. The corresponding FHIR resource for body weight is a vital sign FHIR Observation. Since it must be determined to which program stage FHIR Observation that contains a body weight belongs to, there must be a business rule that decides this. For the birth weight the body weight must be given at the day of the birth or at least one day afterwards (after period days is 1). For the infant weight the body weight must be given on the 6th day (start of program stage) or at least on the 7th day (after period days is 1, since it is calculated from the original start day of the program stage). If a body weight between the 2nd day or the 5th day or after the 7th is received, it must be used. When using the import of the FHIR Adapter, the FHIR Observation is simply filter out. When using the REST interfaces of the FHIR Adapter, an appropriate error message is returned (business rules of the server are violated in this case).

Create rule for birth program stage that uses the birth weight from body weight (linked applicable code set) and link it to transformer scripts for body weight with unit grams. For the transformation from DHIS 2 to FHIR the weight unit is not relevant (as long no specific FHIR profile must be fulfilled). The specified data element reference will be passed to the script.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/programStageRules/097d9ee0-bdb3-44ae-b961-3b4584bad1db -d '{
  "name": "Child Programme: Birth Weight from Body Weight",
  "enabled": true,
  "evaluationOrder": 0,
  "dhisResourceType": "PROGRAM_STAGE_EVENT",
  "fhirResourceType": "OBSERVATION",
  "impEnabled": true,
  "expEnabled": true,
  "fhirCreateEnabled": true,
  "fhirUpdateEnabled": true,
  "fhirDeleteEnabled": true,
  "dhisDataReferences": [
    {
      "dataReference": {
        "value": "DE_2005736",
        "type": "CODE"
      },
      "scriptArgName": "dataElement",
      "required": true
    }
  ],
  "enrollmentCreationEnabled": true,
  "eventCreationEnabled": true,
  "afterPeriodDayType": "ORIG_DUE_DATE",
  "afterPeriodDays": 1,
  "programStage": "http://localhost:8081/api/trackerProgramStages/4c074c85-be49-4b9d-8973-9e16b9615dad",
  "applicableCodeSet": "http://localhost:8081/api/codeSets/d37dfecb-ce88-4fa4-9a78-44ffe874c140",
  "transformImpScript": "http://localhost:8081/api/executableScripts/06005c16-cbc8-4a50-abb0-7b16140c109c",
  "transformExpScript": "http://localhost:8081/api/executableScripts/ddc7c612-aabb-4ec4-bd63-6d5220cf666f"
}'

Create rule that uses the birth weight from body weight and link it to transformer scripts for body weight with unit grams. For the transformation from DHIS 2 to FHIR the weight unit is not relevant (as long no specific FHIR profile must be fulfilled). The specified data element reference will be passed to the script.

curl -XPUT -u admin:district -H 'Content-Type: application/json' http://localhost:8081/api/programStageRules/a6636c83-f236-48cd-bb2b-592147db9a34 -d '{
  "name": "Child Programme: Infant Weight",
  "enabled": true,
  "evaluationOrder": 10,
  "dhisResourceType": "PROGRAM_STAGE_EVENT",
  "fhirResourceType": "OBSERVATION",
  "impEnabled": true,
  "expEnabled": true,
  "fhirCreateEnabled": true,
  "fhirUpdateEnabled": true,
  "fhirDeleteEnabled": true,
  "dhisDataReferences": [
    {
      "dataReference": {
        "value": "DE_2006099",
        "type": "CODE"
      },
      "scriptArgName": "dataElement",
      "required": true
    }
  ],
  "enrollmentCreationEnabled": true,
  "eventCreationEnabled": true,
  "beforePeriodDayType": "ORIG_DUE_DATE",
  "afterPeriodDayType": "ORIG_DUE_DATE",
  "afterPeriodDays": 1,
  "programStage": "http://localhost:8081/api/trackerProgramStages/526b4e01-7747-47ef-a25d-f32ccd739e87",
  "applicableCodeSet": "http://localhost:8081/api/codeSets/d37dfecb-ce88-4fa4-9a78-44ffe874c140",
  "transformImpScript": "http://localhost:8081/api/executableScripts/06005c16-cbc8-4a50-abb0-7b16140c109c",
  "transformExpScript": "http://localhost:8081/api/executableScripts/ddc7c612-aabb-4ec4-bd63-6d5220cf666f"
}'

Verification

In order to verify the configuration above, a child will be registered in Connaught Hospital of Sierra Leone demo database. After adding one FHIR Observation with the body weight on the day of the birth, the child must be enrolled automatically into the Children Programme and the first program stage instance must be active. After adding one FHIR Observation with the body weight on the 6th day of life, the second program stage instance must be active as well.

Determine the technical ID of Connaught Hospital in Freetown.

$ curl -u admin:district 'http://localhost:8081/fhir/dstu3/default/Organization?identifier=http%3A%2F%2Fwww.dhis2.org%2Fdhis2-fhir-adapter%2Fsystems%2Forganization-identifier%7COU_278320&_format=json&_pretty=true'
  
{
  "resourceType": "Bundle",
  "id": "bbf4fa01-e944-4112-9f47-e78d7c7e9a4e",
  "meta": {
    "lastUpdated": "2019-03-04T12:40:23.806+01:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "http://localhost:8081/fhir/dstu3/default/Organization?_format=json&_pretty=true&identifier=http%3A%2F%2Fwww.dhis2.org%2Fdhis2-fhir-adapter%2Fsystems%2Forganization-identifier%7COU_278320"
    }
  ],
  "entry": [
    {
      "fullUrl": "http://localhost:8081/fhir/dstu3/default/Organization/ou-ldXIdLNUNEn-d0e1472a05e647c9b36bff1f06fec352",
      "resource": {
        "resourceType": "Organization",
        "id": "ou-ldXIdLNUNEn-d0e1472a05e647c9b36bff1f06fec352",
        "meta": {
          "lastUpdated": "2017-05-22T15:21:48.511+02:00"
        },
        "identifier": [
          {
            "system": "http://www.dhis2.org/dhis2-fhir-adapter/systems/organization-identifier",
            "value": "OU_278320"
          }
        ],
        "active": true,
        "type": [
          {
            "coding": [
              {
                "system": "http://hl7.org/fhir/organization-type",
                "code": "prov"
              }
            ],
            "text": "Facility"
          }
        ],
        "name": "Connaught Hospital"
      }
    }
  ]
}

Create a new patient (the child). The returned technical ID of the Patient is required to create the FHIR Observations. The ID of the managing organisation of the patient must be replaced with the ID that is returned by the previous request.

curl -i -u admin:district -XPOST -H 'Content-Type: application/fhir+json' http://localhost:8081/fhir/dstu3/default/Patient -d '{
  "resourceType": "Patient",
  "identifier": [
      {
          "system": "http://www.dhis2.org/dhis2-fhir-adapter/systems/patient-identifier",
          "value": "827971"
      }
  ],
  "name": [
      {
          "family": "West",
          "given": [
              "Joe",
              "Alan",
              "Scott"
          ]
      }
  ],
  "gender": "male",
  "birthDate": "2019-02-17",
  "address": [
      {
          "text": "Water Road 675 / Apartment 62 / Freetown"
      }
  ],
  "managingOrganization": {
      "reference": "Organization/ou-ldXIdLNUNEn-d0e1472a05e647c9b36bff1f06fec352"
  }
}'

Create the body weight observation on the day of birth.

curl -i -u admin:district -XPOST -H 'Content-Type: application/fhir+json' http://localhost:8081/fhir/dstu3/default/Observation -d '{
  "resourceType": "Observation",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "29463-7",
        "display": "Weight"
      }
    ]
  },
  "subject": {
    "reference": "Patient/te-zfYZ21jxHma-5f9ebdc9852e4c8387ca795946aabc35"
  },
  "effectiveDateTime": "2019-02-17",
  "valueQuantity": {
    "value": 3.010,
    "unit": "kg",
    "system": "http://unitsofmeasure.org",
    "code": "kg"
  }
}'

Create the body weight observation on the day of birth.

curl -i -u admin:district -XPOST -H 'Content-Type: application/fhir+json' http://localhost:8081/fhir/dstu3/default/Observation -d '{
  "resourceType": "Observation",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "29463-7",
        "display": "Weight"
      }
    ]
  },
  "subject": {
    "reference": "Patient/te-zfYZ21jxHma-5f9ebdc9852e4c8387ca795946aabc35"
  },
  "effectiveDateTime": "2019-02-23",
  "valueQuantity": {
    "value": 3200,
    "unit": "g",
    "system": "http://unitsofmeasure.org",
    "code": "g"
  }
}'

Copyright (c) 2004-2019, University of Oslo. All rights reserved.

Home

Version 1.0

Setup

Mappings

API

Version 1.1

API

Profiles

Step by Step Guides

Related Items

Clone this wiki locally