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

DHIS2 FHIR Adapter API Guide for Administration and Mapping (1.0)

Jump to bottom
Volker edited this page Jan 22, 2019 · 1 revision

The content of this page has been generated automatically. The original version of this page can be accessed on a running adapter with the following URL http://localhost:8081/docs/api-guide.html (assuming that the adapter has been installed in the root context of the web application container and the container accepts connections on port 8081 on localhost).

Table of Contents

Overview

HTTP verbs

Verb Usage
GET Used to retrieve a resource
POST Used to create a new resource
PATCH Used to update an existing resource, including partial updates (support for http://jsonpatch.com/and https://tools.ietf.org/html/rfc7386).
DELETE Used to delete an existing resource

HTTP status codes

Status code Usage
200 OK The request completed successfully
201 Created A new resource has been created successfully. The resource's URI is available from the response's Locationheader
204 No Content An update to an existing resource has been applied successfully
400 Bad Request The request was malformed. The response body will include an error providing further information
404 Not Found The requested resource did not exist

Authentication

To use the API authentication is required. Currently only basic authentication is supported. The support will be extended to OAuth2 in the future. The authentication is verified by DHIS 2 and authorities are granted by DHIS 2 as well (mapped by the configuration of the adapter).

API

Enumeration Values

The API re-uses several enumerations. These are described by this section. Enumerations that are used by one one API resource are documented with the corresponding API resource.

Data Type

Data type enumerations are used for defining data the are passed to a script and data that is returned by a script. Some of the data types can also be used for script arguments. In this case there is a string represenation for that data type.

Value Description
BOOLEAN A boolean value. The strings trueand falsecan be used.
INTEGER An integer value without fraction digits. E.g. 10678
STRING A string value.
DOUBLE A double precision floating point value. E.g. -18.83
DATE_TIME A date and time value. E.g. 2018-11-13T20:11:11.204Z
DATE_UNIT A date unit. Possible values are YEARS, MONTHS, DAYS.
GENDER Gender of a person. Possible values are MALE, FEMALE.
WEIGHT_UNIT A weight unit. Possible values are GRAM, KILO_GRAM, OUNCE, POUND.
CONSTANT The code of a constant resource entry. E.g. GENDER_FEMALE.
CODE The code of a code resource entry. E.g. VACCINE_01.
LOCATION A GEO location with longitude and latitude (in specified order). E.g. [-10.212,69.123]
PATTERN A regular expression pattern that may also contain groups. E.g. CODE_(.+)
ORG_UNIT_REF A reference to a organization unit (by unique ID, code or name). E.g. CODE:OU_471827
TRACKED_ENTITY_REF A reference to a tracked entity type (by unique ID or name). E.g. NAME:Person
TRACKED_ENTITY_ATTRIBUTE_REF A reference to a tracked entity attribute (by unique ID, code or name). E.g. ID:1uw827761s21
DATA_ELEMENT_REF A reference to a data element (by unique ID, code or name). E.g. NAME:CP Birth Weight
PROGRAM_REF A reference to a tracker program (by unique ID, name). E.g. NAME:Child Programme
PROGRAM_STAGE_REF A reference to a tracker program stage (bu unique ID, name). E.g. NAME:Birth
FHIR_RESOURCE A FHIR resource as defined by HAPI FHIR API. There is no string representation for this data type.
FHIR_RESOURCE_LIST A list of FHIR resources as defined by HAPI FHIR API. There is no string representation for this data type.
EVENT_DECISION_TYPE A decision that is made before processing an event (tracker program stage instance). Possible values are CONTINUE (use the existing event), NEW_EVENT (create a new event, just for repeatable program stages), BREAK (the complete rule is not applicable).

Resources

Resources can be divided into three groups:

  • Code mapping management.
  • Data mapping management.
  • Adapter administration.

The response body resource examples in this document use by default content type application/hal+json.

Sorting and paging can be achieved as seen below. Read resource sorted and paged curl snippet

$ curl 'http://localhost:8081/api/codes?page=0&size=3&sort=lastUpdatedAt%2Cdesc' -i -u 'admin:district' -X GET

Read resource sorted and paged response body

{
  "_embedded" : {
    "codes" : [ {
      "createdAt" : "2018-11-22T02:33:53.901Z",
      "lastUpdatedBy" : "2h2maqu827d",
      "lastUpdatedAt" : "2018-11-22T02:33:53.901Z",
      "name" : "MMR",
      "code" : "VACCINE_03",
      "mappedCode" : null,
      "description" : "measles, mumps and rubella virus vaccine",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8081/api/codes/71f5536a-2587-45b9-88ac-9aba362a424a"
        },
        "code" : {
          "href" : "http://localhost:8081/api/codes/71f5536a-2587-45b9-88ac-9aba362a424a"
        },
        "codeCategory" : {
          "href" : "http://localhost:8081/api/codes/71f5536a-2587-45b9-88ac-9aba362a424a/codeCategory"
        }
      }
    }, {
      "createdAt" : "2018-11-22T02:33:53.901Z",
      "lastUpdatedBy" : "2h2maqu827d",
      "lastUpdatedAt" : "2018-11-22T02:33:53.901Z",
      "name" : "M/R",
      "code" : "VACCINE_04",
      "mappedCode" : null,
      "description" : "measles and rubella virus vaccine",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8081/api/codes/eac12b34-ddeb-47af-a1de-59ee2dac488f"
        },
        "code" : {
          "href" : "http://localhost:8081/api/codes/eac12b34-ddeb-47af-a1de-59ee2dac488f"
        },
        "codeCategory" : {
          "href" : "http://localhost:8081/api/codes/eac12b34-ddeb-47af-a1de-59ee2dac488f/codeCategory"
        }
      }
    }, {
      "createdAt" : "2018-11-22T02:33:53.900Z",
      "lastUpdatedBy" : "2h2maqu827d",
      "lastUpdatedAt" : "2018-11-22T02:33:53.900Z",
      "name" : "DTaP",
      "code" : "VACCINE_20",
      "mappedCode" : null,
      "description" : "diphtheria, tetanus toxoids and acellular pertussis vaccine",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
        },
        "code" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
        },
        "codeCategory" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187/codeCategory"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8081/api/codes?page=0&size=3&sort=lastUpdatedAt,desc"
    },
    "self" : {
      "href" : "http://localhost:8081/api/codes"
    },
    "next" : {
      "href" : "http://localhost:8081/api/codes?page=1&size=3&sort=lastUpdatedAt,desc"
    },
    "last" : {
      "href" : "http://localhost:8081/api/codes?page=1&size=3&sort=lastUpdatedAt,desc"
    },
    "profile" : {
      "href" : "http://localhost:8081/api/profile/codes"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 5,
    "totalPages" : 2,
    "number" : 0
  }
}
Table 1. Fields for paged code reading
Path Type Description
page Object The paging information.
page.size Number The used page size (may be less than the specified amount).
page.totalElements Number The total amount of elements.
page.totalPages Number The total number of pages.
page.number Number The current page number.
_links Object Links to other resources

Filtering can be done as shown below. Read resource filtered curl snippet

$ curl 'http://localhost:8081/api/codes?name=DTaP' -i -u 'admin:district' -X GET

Read resource filtered response body

{
  "_embedded" : {
    "codes" : [ {
      "createdAt" : "2018-11-22T02:33:53.900Z",
      "lastUpdatedBy" : "2h2maqu827d",
      "lastUpdatedAt" : "2018-11-22T02:33:53.900Z",
      "name" : "DTaP",
      "code" : "VACCINE_20",
      "mappedCode" : null,
      "description" : "diphtheria, tetanus toxoids and acellular pertussis vaccine",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
        },
        "code" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
        },
        "codeCategory" : {
          "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187/codeCategory"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/codes{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8081/api/profile/codes"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Code Mapping Resources

Constant

The constant resource enables mapping of a constant value to a configurable value. E.g. the constant GENDER_MALE can be mapped to the DHIS 2 option set value Male. When another value is used by DHIS 2 (e.g. the letter M for Male), then just the configurable value must be changed. The rules and transformations does not need to be changed. Create resource curl snippet

$ curl 'http://localhost:8081/api/constants' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "category" : "GENDER",
  "name" : "Gender Female",
  "description" : "Constant for Gender option value as it is used by DHIS2.",
  "code" : "GENDER_FEMALE",
  "dataType" : "STRING",
  "value" : "Female"
}'
Table 2. Fields for constant creation
Path Type Description Constraints
name String The unique name of the constant. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the constant. Must not be blank. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the constant is used.
category String The constant category to which the constant belongs to. Must not be null. Supported values are GENDER, OTHER, TEXT_RECOGNITION
dataType String The data type of the constant value. Must not be null. Supported values are BOOLEAN, CODE, CONSTANT, DATA_ELEMENT_REF, DATE_TIME, DATE_UNIT, DOUBLE, EVENT_DECISION_TYPE, FHIR_RESOURCE, FHIR_RESOURCE_LIST, GENDER, INTEGER, LOCATION, ORG_UNIT_REF, PATTERN, PROGRAM_REF, PROGRAM_STAGE_REF, STRING, TRACKED_ENTITY_ATTRIBUTE_REF, TRACKED_ENTITY_REF, WEIGHT_UNIT
value String The value of the constant (must have the specified data type). Size must be between 0 and 250 inclusive

Read resource curl snippet

$ curl 'http://localhost:8081/api/constants/fa4a3a0e-ca46-40e4-b832-3aec96bed55e' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.891Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.891Z",
  "name" : "Gender Male",
  "description" : null,
  "category" : "GENDER",
  "code" : "GENDER_MALE",
  "dataType" : "STRING",
  "value" : "Male",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/constants/fa4a3a0e-ca46-40e4-b832-3aec96bed55e"
    },
    "constant" : {
      "href" : "http://localhost:8081/api/constants/fa4a3a0e-ca46-40e4-b832-3aec96bed55e"
    }
  }
}
Table 3. Fields for constant reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the constant.
code String The unique code of the constant.
description String The detailed description that describes for which purpose the constant is used.
category String The constant category to which the constant belongs to.
dataType String The data type of the constant value.
value String The data type of the constant value (must have the specified data type).
_links Object Links to other resources

Code Category

The code category resource is used to group codes. E.g. a category can be used for defining vaccine codes or organization unit codes. Create resource curl snippet

$ curl 'http://localhost:8081/api/codeCategories' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Test Code Category",
  "code" : "TEST_CODE_CATEGORY",
  "description" : "This is a test code category."
}'
Table 4. Fields for code category creation
Path Type Description Constraints
name String The unique name of the code category. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the code category. Must not be blank. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the code category is used.

Read resource curl snippet

$ curl 'http://localhost:8081/api/codeCategories/8673a315-dd27-4e4c-bb8b-1212808d4ca1' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.886Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.886Z",
  "name" : "Organization Unit",
  "code" : "ORGANIZATION_UNIT",
  "description" : "Includes the mapping for organization units.",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/codeCategories/8673a315-dd27-4e4c-bb8b-1212808d4ca1"
    },
    "codeCategory" : {
      "href" : "http://localhost:8081/api/codeCategories/8673a315-dd27-4e4c-bb8b-1212808d4ca1"
    }
  }
}
Table 5. Fields for code category reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the code category.
code String The unique code of the code category.
description String The detailed description that describes for which purpose the code category is used.
_links Object Links to other resources

Code

The code resource is used to define system independent codes. E.g. one code can be created for a specific vaccine. This code can then be used by rules and transformations. This code can the be mapped to system specific codes (e.g. country dependent vaccine codes). Create resource curl snippet

$ curl 'http://localhost:8081/api/codes' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Test Code",
  "code" : "TEST_CODE",
  "mappedCode" : "MAPPED_TEST_CODE",
  "description" : "This is a test code.",
  "codeCategory" : "http://localhost:8081/api/codeCategories/8673a315-dd27-4e4c-bb8b-1212808d4ca1"
}'
Table 6. Fields for code creation
Path Type Description Constraints
name String The unique name of the code. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the code. Must not be blank. Size must be between 0 and 50 inclusive
mappedCode String The optional mapped code (e.g. organization unit code as it exists on DHIS2). If this is not specified the code itself is used. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the code is used.
codeCategory String The reference to the code category to which this code belongs to. Must not be null

Read resource curl snippet

$ curl 'http://localhost:8081/api/codes/348d9391-c770-4853-8cdf-f3c5c6830485' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.890Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.890Z",
  "name" : "Central Hospital Freetown",
  "code" : "OU_FT_CH",
  "mappedCode" : "OU_6125",
  "description" : "Organization unit Central Hospital in Freetown.",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/codes/348d9391-c770-4853-8cdf-f3c5c6830485"
    },
    "code" : {
      "href" : "http://localhost:8081/api/codes/348d9391-c770-4853-8cdf-f3c5c6830485"
    },
    "codeCategory" : {
      "href" : "http://localhost:8081/api/codes/348d9391-c770-4853-8cdf-f3c5c6830485/codeCategory"
    }
  }
}
Table 7. Fields for code reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the code.
code String The unique code of the code.
mappedCode String The optional mapped code (e.g. organization unit code as it exists on DHIS2). If this is not specified the code itself is used.
description String The detailed description that describes for which purpose the code is used.
_links Object Links to other resources

Code Set

The code category resource is used to group codes for a specific purpose. E.g. a code set can be defined that contains all vaccines that result in a measles immunization. This code set can then be used to check if a rule is applicable to change measles immunization related information of a patient. Create resource curl snippet

$ curl 'http://localhost:8081/api/codeSets' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Vaccine Measles",
  "code" : "ALL_MEASLES",
  "codeCategory" : "http://localhost:8081/api/codeCategories/7090561e-f45b-411e-99c0-65fa1d145018",
  "description" : "All measles vaccine codes.",
  "codeSetValues" : [ {
    "code" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
  }, {
    "code" : "http://localhost:8081/api/codes/02422ddd-b606-4bb6-8d0f-cca090182b5d",
    "enabled" : false
  } ]
}'
Table 8. Fields for code set creation
Path Type Description Constraints
name String The unique name of the code set. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the code set. Must not be blank. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the code set is used.
codeCategory String The code category reference to which the code set belongs to. Must not be null
codeSetValues Array The codes that belong to this code set. Must not be null
codeSetValues[].code String The included code reference (must be unique in the code set).
codeSetValues[].enabled Boolean Specifies if the code is enabled in the code set.

Read resource curl snippet

$ curl 'http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.902Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.902Z",
  "name" : "All DTP/DTaP",
  "code" : "ALL_DTP_DTAP",
  "description" : "All DTP/DTaP vaccines.",
  "codeSetValues" : [ {
    "enabled" : true,
    "_links" : {
      "codeSet" : {
        "href" : "http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558"
      },
      "code" : {
        "href" : "http://localhost:8081/api/codes/f9462e8c-653b-4c6a-a502-8470a1ab2187"
      }
    }
  }, {
    "enabled" : true,
    "_links" : {
      "codeSet" : {
        "href" : "http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558"
      },
      "code" : {
        "href" : "http://localhost:8081/api/codes/02422ddd-b606-4bb6-8d0f-cca090182b5d"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558"
    },
    "codeSet" : {
      "href" : "http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558"
    },
    "codeCategory" : {
      "href" : "http://localhost:8081/api/codeSets/bb66ee91-8e86-422c-bb00-5a90ac95a558/codeCategory"
    }
  }
}
Table 9. Fields for code set reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the code set.
code String The unique code of the code set.
description String The detailed description that describes for which purpose the code set is used.
codeSetValues Array The codes that belong to this code set.
codeSetValues[].enabled Boolean Specifies if the code is enabled in the code set.
_links Object Links to other resources
codeSetValues[]._links Object Links to other resources (e.g. the referenced code)

System

The system resource is used to define coding system. E.g. the CVX standard for vaccine codes is a coding system with a defined system URI. Also the identifier values for national patient identifiers are defined within a coding system. Create resource curl snippet

$ curl 'http://localhost:8081/api/systems' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Sierra Leone Patient",
  "code" : "SYSTEM_SL_PATIENT",
  "description" : "All Sierra Leone patients.",
  "descriptionProtected" : false,
  "systemUri" : "http://example.sl/patients",
  "enabled" : true
}'
Table 10. Fields for system creation
Path Type Description Constraints
name String The unique name of the system. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the system. Must not be blank. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the system is used.
systemUri String The system URI of the system. Must not be blank. Size must be between 0 and 120 inclusive
enabled Boolean Specifies if this system and its code are enabled.
descriptionProtected Boolean Specifies if the description contains license information that must not be changed.

Read resource curl snippet

$ curl 'http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.898Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.898Z",
  "name" : "Sierra Leone Organization",
  "code" : "SYSTEM_SL_ORGANIZATION",
  "systemUri" : "http://example.sl/organizations",
  "enabled" : true,
  "description" : null,
  "descriptionProtected" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3"
    },
    "system" : {
      "href" : "http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3"
    }
  }
}
Table 11. Fields for system reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the system.
code String The unique code of the system.
description String The detailed description that describes for which purpose the system is used.
systemUri String The system URI of the system.
enabled Boolean Specifies if this system and its code are enabled.
descriptionProtected Boolean Specifies if the description contains license information that must not be changed.
_links Object Links to other resources

System Code

The system code resource is used to define system specific codes and map then to internally used codes that are used by rules and transformations. E.g. a system specific code may be a national vaccine code that is mapped to an internal code. Create resource curl snippet

$ curl 'http://localhost:8081/api/systemCodes' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "system" : "http://localhost:8081/api/systems/c4e9ac6a-cc8f-4c73-aab6-0fa6775c0ca3",
  "code" : "http://localhost:8081/api/codes/348d9391-c770-4853-8cdf-f3c5c6830485",
  "systemCode" : "982783729"
}'
Table 12. Fields for system code creation
Path Type Description Constraints
system String The reference to the system to which the code belongs to. Must not be null
systemCode String The code of the system. Must not be blank. Size must be between 0 and 120 inclusive
code String The reference to the internal code that is used for the system specific code. Must not be null

Read resource curl snippet

$ curl 'http://localhost:8081/api/systemCodes/c513935c-9cd2-4357-a679-60f0c79bfacb' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.898Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.898Z",
  "systemCode" : "982737",
  "systemCodeValue" : "http://example.sl/organizations|982737",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/systemCodes/c513935c-9cd2-4357-a679-60f0c79bfacb"
    },
    "systemCode" : {
      "href" : "http://localhost:8081/api/systemCodes/c513935c-9cd2-4357-a679-60f0c79bfacb"
    },
    "code" : {
      "href" : "http://localhost:8081/api/systemCodes/c513935c-9cd2-4357-a679-60f0c79bfacb/code"
    },
    "system" : {
      "href" : "http://localhost:8081/api/systemCodes/c513935c-9cd2-4357-a679-60f0c79bfacb/system"
    }
  }
}
Table 13. Fields for system code reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
systemCode String The code of the system.
systemCodeValue String The combination of system URI and code separated by a pipe character (generated, cannot be updated).
_links Object Links to other resources

Data Mapping Resources

Script

The script resource defines a single script with a specific purpose. The script itself cannot be executed. Only executable scripts can be executed. There may be more than one executable script for one script (using different script argument values). The purpose may be a evaluation (e.g. calculating a specific date) or a transformation (e.g. transformation from FHIR patient to DHIS 2 tracked entity instance). For one script there may be several script sources (one for each supported FHIR version). A single script source can also handle multiple FHIR versions. One script may have several arguments that are passed as a single map variable to the script. The script may require further variables to execute. Create resource curl snippet

$ curl 'http://localhost:8081/api/scripts' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Transforms FHIR Immunization to Y/N data element",
  "code" : "TRANSFORM_FHIR_IMMUNIZATION_YN",
  "description" : "Transforms FHIR Immunization to Y/N data element.",
  "scriptType" : "TRANSFORM_TO_DHIS",
  "returnType" : "BOOLEAN",
  "inputType" : "FHIR_IMMUNIZATION",
  "outputType" : "DHIS_EVENT",
  "variables" : [ "CONTEXT", "INPUT", "OUTPUT" ]
}'
Table 14. Fields for script creation
Path Type Description Constraints
name String The unique name of the script. Must not be blank. Size must be between 0 and 230 inclusive
code String The unique code of the script. Must not be blank. Size must be between 0 and 50 inclusive
description String The detailed description that describes for which purpose the script is used.
scriptType String The the of the script that describes its purpose. Must not be null. Supported values are EVALUATE, TRANSFORM_TO_DHIS
returnType String The data type of the value that is returned by the script. Must not be null. Supported values are BOOLEAN, CODE, CONSTANT, DATA_ELEMENT_REF, DATE_TIME, DATE_UNIT, DOUBLE, EVENT_DECISION_TYPE, FHIR_RESOURCE, FHIR_RESOURCE_LIST, GENDER, INTEGER, LOCATION, ORG_UNIT_REF, PATTERN, PROGRAM_REF, PROGRAM_STAGE_REF, STRING, TRACKED_ENTITY_ATTRIBUTE_REF, TRACKED_ENTITY_REF, WEIGHT_UNIT
inputType String The required data type of the transformation input. Supported values are DHIS_ENROLLMENT, DHIS_EVENT, DHIS_TRACKED_ENTITY_INSTANCE, FHIR_DIAGNOSTIC_REPORT, FHIR_IMMUNIZATION, FHIR_OBSERVATION, FHIR_PATIENT, FHIR_RELATED_PERSON
outputType String The required data type of the transformation output. Supported values are DHIS_ENROLLMENT, DHIS_EVENT, DHIS_TRACKED_ENTITY_INSTANCE, FHIR_DIAGNOSTIC_REPORT, FHIR_IMMUNIZATION, FHIR_OBSERVATION, FHIR_PATIENT, FHIR_RELATED_PERSON
variables Array The variables that are required for the script execution.

Read resource curl snippet

$ curl 'http://localhost:8081/api/scripts/f18acd12-bc85-4f79-935d-353904eadc0b' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.891Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.891Z",
  "name" : "Transforms FHIR Immunization to option set data element",
  "description" : "Transforms FHIR Immunization to an option set data element.",
  "code" : "TRANSFORM_FHIR_IMMUNIZATION_OS",
  "scriptType" : "TRANSFORM_TO_DHIS",
  "returnType" : "BOOLEAN",
  "inputType" : "FHIR_IMMUNIZATION",
  "outputType" : "DHIS_EVENT",
  "variables" : [ "CONTEXT", "INPUT", "OUTPUT" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/scripts/f18acd12-bc85-4f79-935d-353904eadc0b"
    },
    "script" : {
      "href" : "http://localhost:8081/api/scripts/f18acd12-bc85-4f79-935d-353904eadc0b"
    },
    "arguments" : {
      "href" : "http://localhost:8081/api/scripts/f18acd12-bc85-4f79-935d-353904eadc0b/arguments"
    },
    "sources" : {
      "href" : "http://localhost:8081/api/scripts/f18acd12-bc85-4f79-935d-353904eadc0b/sources"
    }
  }
}
Table 15. Fields for script reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the script.
code String The unique code of the script.
description String The detailed description that describes for which purpose the script is used.
scriptType String The the of the script that describes its purpose.
returnType String The data type of the value that is returned by the script.
inputType String The required data type of the transformation input.
outputType String The required data type of the transformation output.
variables Array The variables that are required for the script execution.
_links Object Links to other resources

Script Argument

The script argument resource defines a single script argument that belongs to a script. Event of the script argument is marked as mandatory, providing a value is not required. The final value must be specified by the executable script argument in this case. The provided default argument value is only used when the executable script does not define any override value for that argument Create resource curl snippet

$ curl 'http://localhost:8081/api/scriptArgs' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "script" : "http://localhost:8081/api/script/f1da6937-e2fe-47a4-b0f3-8bbff7818ee1",
  "name" : "weightUnit",
  "description" : "The resulting weight unit in which the value will be set on the data element.",
  "dataType" : "WEIGHT_UNIT",
  "mandatory" : true,
  "array" : false,
  "defaultValue" : "KILO_GRAM"
}'
Table 16. Fields for script argument creation
Path Type Description Constraints
script String The reference to the script resource to which this argument belongs to. Must not be null
name String The name of the script argument. This is also used inside the script source to access the argument value. Must not be blank. Size must be between 0 and 30 inclusive
description String The detailed description of the purpose of the argument.
dataType String The data type of the argument value. Must not be null. Supported values are BOOLEAN, CODE, CONSTANT, DATA_ELEMENT_REF, DATE_TIME, DATE_UNIT, DOUBLE, EVENT_DECISION_TYPE, FHIR_RESOURCE, FHIR_RESOURCE_LIST, GENDER, INTEGER, LOCATION, ORG_UNIT_REF, PATTERN, PROGRAM_REF, PROGRAM_STAGE_REF, STRING, TRACKED_ENTITY_ATTRIBUTE_REF, TRACKED_ENTITY_REF, WEIGHT_UNIT
array Boolean Specifies if the argument contains an array of values. The values must be separated by a pipe character.
mandatory Boolean Specifies if the argument is mandatory and cannot be null when the script is executed.
defaultValue String The default value of the argument. This may be overridden by the executable script. The value must be convertible to the specified data type. If the argument is an array, the array values must be separated by pipe characters.

Read resource curl snippet

$ curl 'http://localhost:8081/api/scriptArgs/d8cd0e7d-7780-45d1-8094-b448b480e6b8' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.897Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.897Z",
  "name" : "round",
  "dataType" : "BOOLEAN",
  "mandatory" : true,
  "array" : false,
  "defaultValue" : "true",
  "description" : "Specifies if the resulting value should be rounded.",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/scriptArgs/d8cd0e7d-7780-45d1-8094-b448b480e6b8"
    },
    "scriptArg" : {
      "href" : "http://localhost:8081/api/scriptArgs/d8cd0e7d-7780-45d1-8094-b448b480e6b8"
    },
    "script" : {
      "href" : "http://localhost:8081/api/scriptArgs/d8cd0e7d-7780-45d1-8094-b448b480e6b8/script"
    }
  }
}
Table 17. Fields for script argument reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The name of the script argument. This is also used inside the script source to access the argument value.
description String The detailed description of the purpose of the argument.
dataType String The data type of the argument value.
array Boolean Specifies if the argument contains an array of values. The values must be separated by a pipe character.
mandatory Boolean Specifies if the argument is mandatory and cannot be null when the script is executed.
defaultValue String Specifies if the argument is mandatory and cannot be null when the script is executed.
_links Object Links to other resources

Script Source

The source code of the script. There may be a source for each supported FHIR version at most. Create resource curl snippet

$ curl 'http://localhost:8081/api/scriptSources' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "script" : "http://localhost:8081/api/script/f1da6937-e2fe-47a4-b0f3-8bbff7818ee1",
  "sourceType" : "JAVASCRIPT",
  "sourceText" : "output.setValue(args['dataElement'], vitalSignUtils.getWeight(input.value, args['weightUnit'], args['round']), null, args['override'], context.getFhirRequest().getLastUpdated())",
  "fhirVersions" : [ "DSTU3" ]
}'
Table 18. Fields for script source creation
Path Type Description Constraints
script String The reference to the script to which this source belongs to. Must not be null
sourceType String The type of the source code (the programming language). Must not be null. Supported values are JAVASCRIPT
sourceText String The code of the script in the configured programming language (source type). Must not be blank
fhirVersions Array The FHIR versions that are supported by this script source. Must not be null. Size must be between 1 and 2147483647 inclusive

Read resource curl snippet

$ curl 'http://localhost:8081/api/scriptSources/081c4642-bb83-44ab-b90f-aa206ad347aa' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.894Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.894Z",
  "sourceText" : "output.setIntegerOptionValue(args['dataElement'], immunizationUtils.getMaxDoseSequence(input), 1, false, args['optionValuePattern'], (input.hasPrimarySource()?!input.getPrimarySource():null))",
  "sourceType" : "JAVASCRIPT",
  "fhirVersions" : [ "DSTU3" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/scriptSources/081c4642-bb83-44ab-b90f-aa206ad347aa"
    },
    "scriptSource" : {
      "href" : "http://localhost:8081/api/scriptSources/081c4642-bb83-44ab-b90f-aa206ad347aa"
    },
    "script" : {
      "href" : "http://localhost:8081/api/scriptSources/081c4642-bb83-44ab-b90f-aa206ad347aa/script"
    }
  }
}
Table 19. Fields for script source reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
sourceType String The type of the source code (the programming language).
sourceText String The code of the script in the configured programming language (source type).
fhirVersions Array The FHIR versions that are supported by this script source.
_links Object Links to other resources

Executable Script

The executable script resource provides the ability to create an executable script for a script. There may be more than one executable script for one script. Each executable script can override the script argument values of the original scripts. E.g. a script may define an argument for the data element reference and the unit for the weight of the person. The script may not define a default value for the data element, but a default value for the unit (e.g. kilogram). The executable script that processes the weight of a new born child must then define the value for the data element reference and may override the unit (e.g. gram because weight precision for a new born child). Create resource curl snippet

$ curl 'http://localhost:8081/api/executableScripts' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "script" : "http://localhost:8081/api/script/f1da6937-e2fe-47a4-b0f3-8bbff7818ee1",
  "name" : "CP: Birth Weight",
  "code" : "CP_BIRTH_WEIGHT",
  "overrideArguments" : [ {
    "argument" : "http://localhost:8081/api/scriptArgs/07679199-59ae-4530-9411-ac5814102372",
    "overrideValue" : "CODE:DE_2005736",
    "enabled" : true
  }, {
    "argument" : "http://localhost:8081/api/scriptArgs/d8cd0e7d-7780-45d1-8094-b448b480e6b8",
    "overrideValue" : "false",
    "enabled" : true
  } ]
}'
Table 20. Fields for executable script creation
Path Type Description Constraints
script String The reference to the script resource that is executed by this resource definition. Must not be null
name String The name of the executable script. Must not be blank. Size must be between 0 and 230 inclusive
code String The code of the executable script. Must not be blank. Size must be between 0 and 100 inclusive
description String The detailed description of the purpose of the executable script.
overrideArguments Array The overridden arguments of the script resource. If the script resource defined mandatory arguments with null values, these must be specified for the executable script. Otherwise the script cannot be executed. If no argument value should be overridden, this field need not to be specified.
overrideArguments[].argument String Reference to the script argument resource for which the value should be overridden.
overrideArguments[].overrideValue String The value that should be used for the argument when executing the script. The value must match the data type of the argument.
overrideArguments[].enabled Boolean Specifies if the override argument is enabled. If the override argument is not enabled, the value of the script argument itself is used.

Read resource curl snippet

$ curl 'http://localhost:8081/api/executableScripts/1a2950cf-0842-4dd3-9453-284fb08789d3' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.895Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.895Z",
  "name" : "CP: OPV Dose",
  "code" : "CP_OPV_DOSE",
  "description" : "Transforms FHIR Immunization for OPV vaccines.",
  "overrideArguments" : [ {
    "overrideValue" : "CODE:DE_2006104",
    "enabled" : true,
    "_links" : {
      "argument" : {
        "href" : "http://localhost:8081/api/scriptArgs/44134ba8-d77f-4c4d-90c6-b434ffbe7958"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/executableScripts/1a2950cf-0842-4dd3-9453-284fb08789d3"
    },
    "executableScript" : {
      "href" : "http://localhost:8081/api/executableScripts/1a2950cf-0842-4dd3-9453-284fb08789d3"
    },
    "script" : {
      "href" : "http://localhost:8081/api/executableScripts/1a2950cf-0842-4dd3-9453-284fb08789d3/script"
    }
  }
}
Table 21. Fields for executable script reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The name of the executable script.
code String The code of the executable script.
description String The detailed description of the purpose of the executable script.
overrideArguments Array The overridden arguments of the script resource. If the script resource defined mandatory arguments with null values, these must be specified for the executable script. Otherwise the script cannot be executed. If no argument value should be overridden, this field need not to be specified.
overrideArguments[].overrideValue String The value that should be used for the argument when executing the script. The value must match the data type of the argument.
overrideArguments[].enabled Boolean Specifies if the override argument is enabled. If the override argument is not enabled, the value of the script argument itself is used.
_links Object Links to other resources
overrideArguments[]._links Object Links to other resources

Tracked Entity

Configures the reference to a DHIS 2 tracked entity type. A tracked entity type must define a unique identifier in order to be able to map FHIR data to existing tracked entity instances. Create resource curl snippet

$ curl 'http://localhost:8081/api/trackedEntities' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Person Tracked Entity (disabled)",
  "description" : "Transforms a FHIR Patient to a Person (obsolete).",
  "enabled" : false,
  "trackedEntityReference" : {
    "value" : "Obsolete Person",
    "type" : "NAME"
  },
  "trackedEntityIdentifierReference" : {
    "value" : "National identifier",
    "type" : "CODE"
  }
}'
Table 22. Fields for tracked entity creation
Path Type Description Constraints
name String The unique name of the rule. Must not be blank. Size must be between 0 and 230 inclusive
description String The detailed description that describes for which purpose the rule is used.
enabled Boolean Specifies if this rule is enabled.
trackedEntityReference Object The reference to the DHIS2 Tracked Entity Type.
trackedEntityReference.value String The unique ID/code/name of the Tracked Entity Type.
trackedEntityReference.type String The type of reference value of the Tracked Entity Type.
trackedEntityIdentifierReference Object The reference to the DHIS2 Tracked Entity Attribute that is used as national identifier.
trackedEntityIdentifierReference.value String The unique ID/code/name of the Tracked Entity Attribute.
trackedEntityIdentifierReference.type String The type of reference value of the Tracked Entity Attribute.

Read resource curl snippet

$ curl 'http://localhost:8081/api/trackedEntities/4203754d-2177-4a44-86aa-2de31ee4c8ee' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.915Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.915Z",
  "name" : "Person",
  "description" : "Tracked entity for a patient.",
  "enabled" : true,
  "trackedEntityReference" : {
    "value" : "Person",
    "type" : "NAME"
  },
  "trackedEntityIdentifierReference" : {
    "value" : "National identifier",
    "type" : "CODE"
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/trackedEntities/4203754d-2177-4a44-86aa-2de31ee4c8ee"
    },
    "trackedEntity" : {
      "href" : "http://localhost:8081/api/trackedEntities/4203754d-2177-4a44-86aa-2de31ee4c8ee"
    }
  }
}
Table 23. Fields for tracked entity reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the rule.
description String The detailed description that describes for which purpose the rule is used.
enabled Boolean Specifies if this rule is enabled.
trackedEntityReference Object The reference to the DHIS2 Tracked Entity Type.
trackedEntityReference.value String The unique ID/code/name of the Tracked Entity Type.
trackedEntityReference.type String The type of reference value of the Tracked Entity Type.
trackedEntityIdentifierReference Object The reference to the DHIS2 Tracked Entity Attribute that is used as national identifier.
trackedEntityIdentifierReference.value String The unique ID/code/name of the Tracked Entity Attribute.
trackedEntityIdentifierReference.type String The type of reference value of the Tracked Entity Attribute.
_links Object Links to other resources

Tracked Entity Rule

The tracked entity rule resource defines a rule that is able to transform a FHIR resource that a DHIS 2 tracked entity instance. Create resource curl snippet

$ curl 'http://localhost:8081/api/rules' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "FHIR Patient to Person (disabled)",
  "description" : "Transforms a FHIR Patient to a Person",
  "enabled" : false,
  "evaluationOrder" : 0,
  "dhisResourceType" : "TRACKED_ENTITY",
  "fhirResourceType" : "PATIENT",
  "applicableInScript" : null,
  "applicableCodeSet" : null,
  "trackedEntity" : "http://localhost:8081/api/trackedEntities/4203754d-2177-4a44-86aa-2de31ee4c8ee",
  "transformInScript" : "http://localhost:8081/api/executableScripts/72451c8f-7492-4707-90b8-a3e0796de19e",
  "orgUnitLookupScript" : "http://localhost:8081/api/executableScripts/25a97bb4-7b39-4ed4-8677-db4bcaa28ccf",
  "locationLookupScript" : "http://localhost:8081/api/executableScripts/ef90531f-4438-48bd-83b3-6370dd65875a"
}'
Table 24. Fields for rule creation
Path Type Description Constraints
name String The unique name of the rule. Must not be blank. Size must be between 0 and 230 inclusive
description String The detailed description that describes for which purpose the rule is used.
dhisResourceType String The type of the rule and the type of the data that is stored in DHIS2. Must not be null. Supported values are ENROLLMENT, PROGRAM_STAGE_EVENT, TRACKED_ENTITY
fhirResourceType String The FHIR resource type of the incoming resource. Must not be null. Supported values are DIAGNOSTIC_REPORT, IMMUNIZATION, LOCATION, MEDICATION_REQUEST, OBSERVATION, ORGANIZATION, PATIENT, RELATED_PERSON
enabled Boolean Specifies if this rule is enabled.
evaluationOrder Number Specifies the precedence of this rule when several rules match. Higher values define a higher precedence.
applicableCodeSet String Link to the code set reference that is used to check if the incoming request is applicable for this rule.
applicableInScript String Link to the executable script reference that is used to check if the incoming request is applicable for this rule. The script must be an evaluation script that returns a boolean value.
transformInScript String Link to the executable script reference that is used to transform the FHIR resource input to the DHIS2 resource. Must not be null
trackedEntity String The reference to the DHIS2 Tracked Entity resource. Must not be null
orgUnitLookupScript String Link to the executable script reference that is used to extract the organization unit reference. The script must be an evaluation script that return a reference.
locationLookupScript String Link to the executable script reference that is used to extract the location reference. The script must be an evaluation script that return a location (geo coordinates).
teiLookupScript String Link to the executable script reference that is used to extract the tracked entity related FHIR resource from the input. The script must be an evaluation script that returns a FHIR resource.

Read resource curl snippet

$ curl 'http://localhost:8081/api/rules/5f9ebdc9-852e-4c83-87ca-795946aabc35' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.915Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.915Z",
  "name" : "FHIR Patient to Person",
  "description" : null,
  "enabled" : true,
  "evaluationOrder" : 1,
  "dhisResourceType" : "TRACKED_ENTITY",
  "fhirResourceType" : "PATIENT",
  "containedAllowed" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35"
    },
    "trackedEntityRule" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35"
    },
    "orgUnitLookupScript" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/orgUnitLookupScript"
    },
    "trackedEntity" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/trackedEntity"
    },
    "applicableCodeSet" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/applicableCodeSet"
    },
    "teiLookupScript" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/teiLookupScript"
    },
    "locationLookupScript" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/locationLookupScript"
    },
    "applicableInScript" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/applicableInScript"
    },
    "transformInScript" : {
      "href" : "http://localhost:8081/api/trackedEntityRules/5f9ebdc9-852e-4c83-87ca-795946aabc35/transformInScript"
    }
  }
}
Table 25. Fields for rule reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The unique name of the rule.
description String The detailed description that describes for which purpose the rule is used.
dhisResourceType String The type of the rule and the type of the data that is stored in DHIS2.
fhirResourceType String The FHIR resource type of the incoming resource.
enabled Boolean Specifies if this rule is enabled.
evaluationOrder Number Specifies the precedence of this rule when several rules match. Higher values define a higher precedence.
containedAllowed Boolean Specified if this rule can process contained resources.
_links Object Links to other resources

Adapter Administration Resources

Remote Subscription

The remote subscription resource defines a single remote FHIR server and its subscriptions for FHIR resources. Create resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptions' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Main Subscription",
  "code" : "MAIN_SUBSCRIPTION",
  "description" : "Main FHIR service on which the adapter has subscriptions.",
  "enabled" : true,
  "locked" : false,
  "fhirVersion" : "DSTU3",
  "toleranceMillis" : 2000,
  "autoCreatedSubscriptionResources" : [ "PATIENT" ],
  "adapterEndpoint" : {
    "baseUrl" : "http://localhist:8081",
    "subscriptionType" : "REST_HOOK",
    "authorizationHeader" : "Bearer 98a7558102b7bdc4da5c8f74ca63958c498b4bd9231bd3b0cc"
  },
  "dhisEndpoint" : {
    "authenticationMethod" : "BASIC",
    "username" : "admin",
    "password" : "district"
  },
  "fhirEndpoint" : {
    "baseUrl" : "http://localhost:8082/hapi-fhir-jpaserver-example/baseDstu3",
    "headers" : [ {
      "name" : "Authorization",
      "value" : "Bearer 1196cc744b416a2b91c8239c1a1e251c139d2a89df86427241",
      "secure" : true
    } ]
  }
}'
Table 26. Fields for remote subscription creation
Path Type Description Constraints
name String The name of the remote subscription. Must not be blank. Size must be between 0 and 50 inclusive
code String The code of the remote subscription. Must not be blank. Size must be between 0 and 20 inclusive
description String The detailed description of the purpose of the remote subscription.
enabled Boolean Specifies if this remote subscription has been enabled. If the remote subscription has not been enabled, no subscription notifications are processed from the corresponding FHIR service.
locked Boolean Specifies if this remote subscription has been locked. If the remote subscription has been locked (i.e. by automatic processes), no subscription notifications are processed from the corresponding FHIR service.
fhirVersion String The FHIR version that should be used when communicating with the remote FHIR service. Must not be null. Supported values are DSTU3
toleranceMillis Number The number of milli-seconds to subtract from the last updated timestamp when searching for created and updated resources. Must be at least 0
autoCreatedSubscriptionResources Array Subscription resources for which the subscriptions should be created automatically when creating the subscription resource. This value will not be returned and can only be used when creating and updating the entity. Supported values are PATIENT, RELATED_PERSON
adapterEndpoint Object Specifies remote subscription settings that are relevant for the adapter. Must not be null
adapterEndpoint.baseUrl String The base URL of the adapter that is used to register the subscription on the FHIR service. If the FHIR service runs on a different server, the URL must not contain localhost. If this URL is not specified it is calculated automatically.
adapterEndpoint.subscriptionType String The subscription type that is used to register the subscription on FHIR service. A normal REST hook subscription is sufficient (without any payload). If this causes issues on the FHIR service also a subscription with payload can be used.
adapterEndpoint.authorizationHeader String The authorization header value that is expected by the adapter when it receives a subscription notification from the FHIR service. This should include a bearer token.
dhisEndpoint Object Specifies remote subscription settings that are relevant for the connection to DHIS2. Must not be null
dhisEndpoint.authenticationMethod String The authentication method that should be used when connecting to DHIS2.
dhisEndpoint.username String The username that is used to connect to DHIS2 when handling data of this remote subscription.
dhisEndpoint.password String The password that is used to connect to DHIS2 when handling data of this remote subscription. This value will not be returned and will be set using the original value when performing an update without this value.
fhirEndpoint Object Specifies remote subscription settings that are relevant for the connection to FHIR. Must not be null
fhirEndpoint.baseUrl String The base URL of the FHIR endpoints on the FHIR service.
fhirEndpoint.headers Array The headers that are sent to the remote FHIR service when connecting to the FHIR endpoints.
fhirEndpoint.headers[].name String The name of the header for which the value will be sent (e.g. Authorization).
fhirEndpoint.headers[].value String The value of the header for which the value will be sent (e.g. a bearer token). If the value of the header is marked as secure, the value will not be returned and will be set using the original value when performing an update without this value.
fhirEndpoint.headers[].secure Boolean Specifies if the value of the header is secure and should not be returned (e.g. when it contains authentication information).

Read resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.899Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.899Z",
  "name" : "HAPI FHIR JPA Server",
  "code" : "DEFAULT_SUBSCRIPTION",
  "enabled" : true,
  "locked" : false,
  "description" : "HAPI FHIR JPA Server.",
  "fhirVersion" : "DSTU3",
  "toleranceMillis" : 60000,
  "dhisEndpoint" : {
    "authenticationMethod" : "BASIC",
    "username" : "admin"
  },
  "fhirEndpoint" : {
    "baseUrl" : "http://localhost:8082/hapifhirjpaserverexample/baseDstu3",
    "logging" : false,
    "verboseLogging" : false,
    "headers" : [ {
      "name" : "Authorization",
      "secure" : true
    } ]
  },
  "adapterEndpoint" : {
    "baseUrl" : "http://localhost:8081",
    "authorizationHeader" : "Bearer jhsj832jDShf8ehShdu7ejhDhsilwmdsgs",
    "subscriptionType" : "REST_HOOK_WITH_JSON_PAYLOAD"
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f"
    },
    "remoteSubscription" : {
      "href" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f"
    },
    "systems" : {
      "href" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f/systems"
    },
    "resources" : {
      "href" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f/resources"
    }
  }
}
Table 27. Fields for remote subscription reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
name String The name of the remote subscription.
code String The code of the remote subscription.
description String The detailed description of the purpose of the remote subscription.
enabled Boolean Specifies if this remote subscription has been enabled. If the remote subscription has not been enabled, no subscription notifications are processed from the corresponding FHIR service.
locked Boolean Specifies if this remote subscription has been locked. If the remote subscription has been locked (i.e. by automatic processes), no subscription notifications are processed from the corresponding FHIR service.
fhirVersion String The FHIR version that should be used when communicating with the remote FHIR service.
toleranceMillis Number The number of milli-seconds to subtract from the last updated timestamp when searching for created and updated resources.
autoCreatedSubscriptionResources Array Subscription resources for which the subscriptions should be created automatically when creating the subscription resource. This value will not be returned and can only be used when creating and updating the entity.
adapterEndpoint Object Specifies remote subscription settings that are relevant for the adapter.
adapterEndpoint.baseUrl String The base URL of the adapter that is used to register the subscription on the FHIR service. If the FHIR service runs on a different server, the URL must not contain localhost. If this URL is not specified it is calculated automatically.
adapterEndpoint.subscriptionType String The subscription type that is used to register the subscription on FHIR service. A normal REST hook subscription is sufficient (without any payload). If this causes issues on the FHIR service also a subscription with payload can be used.
adapterEndpoint.authorizationHeader String The authorization header value that is expected by the adapter when it receives a subscription notification from the FHIR service. This should include a bearer token.
dhisEndpoint Object Specifies remote subscription settings that are relevant for the connection to DHIS2.
dhisEndpoint.authenticationMethod String The authentication method that should be used when connecting to DHIS2.
dhisEndpoint.username String The username that is used to connect to DHIS2 when handling data of this remote subscription.
dhisEndpoint.password String The password that is used to connect to DHIS2 when handling data of this remote subscription. This value will not be returned and will be set using the original value when performing an update without this value.
fhirEndpoint Object Specifies remote subscription settings that are relevant for the connection to FHIR.
fhirEndpoint.baseUrl String The base URL of the FHIR endpoints on the FHIR service.
fhirEndpoint.logging Boolean Specifies if basic logging should be enabled when communicating with the FHIR endpoints of this FHIR service.
fhirEndpoint.verboseLogging Boolean Specifies if verbose logging (includes complete pazload) should be enabled when communicating with the FHIR endpoints of this FHIR service. Enabling verbose logging may log confidential patient data. This could violate data protection laws and regulations.
fhirEndpoint.headers Array The headers that are sent to the remote FHIR service when connecting to the FHIR endpoints.
fhirEndpoint.headers[].name String The name of the header for which the value will be sent (e.g. Authorization).
fhirEndpoint.headers[].value String The value of the header for which the value will be sent (e.g. a bearer token). If the value of the header is marked as secure, the value will not be returned and will be set using the original value when performing an update without this value.
fhirEndpoint.headers[].secure Boolean Specifies if the value of the header is secure and should not be returned (e.g. when it contains authentication information).
_links Object Links to other resources

Remote Subscription Resource

The resource for remote subscription resources defines a single subscription for a single specific FHIR resource on a single FHIR server. Create resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptionResources' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "remoteSubscription" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f",
  "fhirResourceType" : "IMMUNIZATION",
  "description" : "Subscription for all immunizations.",
  "fhirCriteriaParameters" : null
}'
Table 28. Fields for script source creation
Path Type Description Constraints
remoteSubscription String The reference to the remote subscription to which this resource belongs to. Must not be null
fhirResourceType String The type of the subscribed FHIR resource. Must not be null. Supported values are DIAGNOSTIC_REPORT, IMMUNIZATION, LOCATION, MEDICATION_REQUEST, OBSERVATION, ORGANIZATION, PATIENT, RELATED_PERSON
description String The detailed description of the purpose of the subscribed FHIR resource.
fhirCriteriaParameters String The prefix that should be added to the codes when mapping them to DHIS2. Size must be between 0 and 200 inclusive

Read resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptionResources/667bfa41-867c-4796-86b6-eb9f9ed4dc94' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.899Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.899Z",
  "fhirResourceType" : "PATIENT",
  "fhirCriteriaParameters" : "_format=json",
  "description" : "Subscription for all Patients.",
  "virtual" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionResources/667bfa41-867c-4796-86b6-eb9f9ed4dc94"
    },
    "remoteSubscriptionResource" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionResources/667bfa41-867c-4796-86b6-eb9f9ed4dc94"
    },
    "remoteSubscription" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionResources/667bfa41-867c-4796-86b6-eb9f9ed4dc94/remoteSubscription"
    }
  }
}
Table 29. Fields for remote subscription resource reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
fhirResourceType String The type of the subscribed FHIR resource.
description String The detailed description of the purpose of the subscribed FHIR resource.
fhirCriteriaParameters String The prefix that should be added to the codes when mapping them to DHIS2.
virtual Boolean Specifies that there is no subscription for this FHIR resource since the FHIR service may not accept subscription for this resource type (just available as contained resources).
hirSubscriptionId String The ID of the automatically created FHIR subscription on the FHIR service.
_links Object Links to other resources

Remote Subscription System

The remote subscription system resource defines a specific coding system that is used for a FHIR resource. E.g. a FHIR system may use system specific codes for patients and organizations. The codes that are provided by several FHIR systems may overlap and are only unique in combination with a FHIR system specific system URI. For each coding system a code prefix can be defined. E.g. if there are ten regions in a country and the ten regions use their own FHIR server than each region may use its own patient identifiers. These patient identifiers can be made unique by adding a specific code prefix (e.g. two letter abbreviation of the regions). This results in a unique national identifier. Create resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptionSystems' -i -u 'admin:district' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "remoteSubscription" : "http://localhost:8081/api/remoteSubscriptions/73cd99c5-0ca8-42ad-a53b-1891fccce08f",
  "fhirResourceType" : "LOCATION",
  "system" : "http://localhost:8081/api/systems/2dd51309-3319-40d2-9a1f-be2a102df4a7",
  "codePrefix" : "LOC_"
}'
Table 30. Fields for script source creation
Path Type Description Constraints
remoteSubscription String The reference to the remote subscription to which this resource belongs to. Must not be null
system String The reference to the system URI that should be mapped to the remote subscription. Must not be null
fhirResourceType String The FHIR resource type to which the system URI should be mapped. Must not be null. Supported values are DIAGNOSTIC_REPORT, IMMUNIZATION, LOCATION, MEDICATION_REQUEST, OBSERVATION, ORGANIZATION, PATIENT, RELATED_PERSON
codePrefix String The prefix that should be added to the codes when mapping them to DHIS2. Size must be between 0 and 20 inclusive

Read resource curl snippet

$ curl 'http://localhost:8081/api/remoteSubscriptionSystems/ea9804a3-9e82-4d0d-9cd2-e417b32b1c0c' -i -u 'admin:district' -X GET

Read resource response body

{
  "createdAt" : "2018-11-22T02:33:53.899Z",
  "lastUpdatedBy" : "2h2maqu827d",
  "lastUpdatedAt" : "2018-11-22T02:33:53.899Z",
  "fhirResourceType" : "ORGANIZATION",
  "codePrefix" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionSystems/ea9804a3-9e82-4d0d-9cd2-e417b32b1c0c"
    },
    "remoteSubscriptionSystem" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionSystems/ea9804a3-9e82-4d0d-9cd2-e417b32b1c0c"
    },
    "remoteSubscription" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionSystems/ea9804a3-9e82-4d0d-9cd2-e417b32b1c0c/remoteSubscription"
    },
    "system" : {
      "href" : "http://localhost:8081/api/remoteSubscriptionSystems/ea9804a3-9e82-4d0d-9cd2-e417b32b1c0c/system"
    }
  }
}
Table 31. Fields for remote subscription system reading
Path Type Description
createdAt String The timestamp when the resource has been created.
lastUpdatedBy String The ID of the user that has updated the user the last time or null if the data has been imported to the database directly.
lastUpdatedAt String The timestamp when the resource has been updated the last time.
fhirResourceType String The FHIR resource type to which the system URI should be mapped.
codePrefix String The prefix that should be added to the codes when mapping them to DHIS2.
_links Object Links to other resources

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