dhis2@7.0.0

create(path, data, params)

destroy(resourceType, path, [data], [options])

get(path, params)

update(resourceType, path, data, [options])

upsert(resourceType, query, data, [options])

This adaptor exports the following namespaced functions:

util.attr(attribute, value)

util.dv(dataElement, value)

util.findAttributeValue(trackedEntity, attributeDisplayName)

util.findAttributeValueById(trackedEntity, attributeUid)

tracker.export(path, query, [options])

tracker.import(strategy, payload, [options])

http.get(path, [options])

http.patch(resourceType, path, data, [options])

http.post(path, data, [options])

http.request(method, path, [options])

This adaptor exports the following from common:

alterState()

cursor()

dataPath()

dataValue()

dateFns

each()

field()

fields()

fn()

fnIf()

group()

http

lastReferenceValue()

merge()

sourceValue()

Functions

create

create(path, data, params) ⇒ Operation

Create a record

Param	Type	Description
path	string	Path to the resource to be created
data	DHIS2Data	An object, or array of objects, to create.
params	object	Optional object of query parameters to include in the request

This operation writes the following keys to state:

State Key	Description
data	The created resource as returned by DHIS2
Example: Create a program

create('programs', {
  name: 'name 20',
  shortName: 'n20',
  programType: 'WITHOUT_REGISTRATION',
});

Example: Create a single event

create('events', {
  program: 'eBAyeGv0exc',
  orgUnit: 'DiszpKrYNg8',
  status: 'COMPLETED',
});

Example: Create a single tracker entity. See Create tracker docs

create('trackedEntities', {
  orgUnit: 'TSyzvBiovKh',
  trackedEntityType: 'nEenWmSyUEp',
  attributes: [
    {
      attribute: 'w75KJ2mc4zz',
      value: 'Gigiwe',
    },
  ]
});

Example: Create a dataSet

create('dataSets', { name: 'OpenFn Data Set', periodType: 'Monthly' });

Example: a dataSetNotification

create('dataSetNotificationTemplates', {
  dataSetNotificationTrigger: 'DATA_SET_COMPLETION',
  notificationRecipient: 'ORGANISATION_UNIT_CONTACT',
  name: 'Notification',
  messageTemplate: 'Hello',
  deliveryChannels: ['SMS'],
  dataSets: [],
});

Example: Create a dataElement

create('dataElements', {
  aggregationType: 'SUM',
  domainType: 'AGGREGATE',
  valueType: 'NUMBER',
  name: 'Paracetamol',
  shortName: 'Para',
});

Example: Create a dataElementGroup

create('dataElementGroups', {
  name: 'Data Element Group 1',
  dataElements: [],
});

Example: Create a dataElementGroupSet

create('dataElementGroupSets', {
  name: 'Data Element Group Set 4',
  dataDimension: true,
  shortName: 'DEGS4',
  dataElementGroups: [],
});

Example: Create a dataValueSet

create('dataValueSets', {
  dataElement: 'f7n9E0hX8qk',
  period: '201401',
  orgUnit: 'DiszpKrYNg8',
  value: '12',
});

Example: Create a dataValueSet with related dataValues

create('dataValueSets', {
  dataSet: 'pBOMPrpg1QX',
  completeDate: '2014-02-03',
  period: '201401',
  orgUnit: 'DiszpKrYNg8',
  dataValues: [
    {
      dataElement: 'f7n9E0hX8qk',
      value: '1',
    },
    {
      dataElement: 'Ix2HsbDMLea',
      value: '2',
    },
    {
      dataElement: 'eY5ehpbEsB7',
      value: '3',
    },
  ],
});

Example: Create an enrollment

create('enrollments', {
  trackedEntity: 'bmshzEacgxa',
  orgUnit: 'TSyzvBiovKh',
  program: 'gZBxv9Ujxg0',
  enrollmentDate: '2013-09-17',
  incidentDate: '2013-09-17',
});

---

destroy

destroy(resourceType, path, [data], [options]) ⇒ Operation

Delete record.

Param	Type	Description
resourceType	string	The type of resource to be deleted. E.g. trackedEntities, organisationUnits, etc.
path	string	Can be an id of an object or path to the nested object to delete.
[data]	Object	Optional. This is useful when you want to remove multiple objects from a collection in one request. You can send data as, for example, {"identifiableObjects": [{"id": "IDA"}, {"id": "IDB"}, {"id": "IDC"}]}. See more on DHIS2 API docs
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request.

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
references	An array of all previous data objects used in the Job
Example: a tracked entity instance. See Delete tracker docs

destroy('trackedEntities', 'LcRd6Nyaq7T');

---

get

get(path, params) ⇒ Operation

Get any resource, as JSON, from DHIS2. Pass in any valid DHIS2 REST path, excluding /api and the version. For the new tracker API, see tracker.export()

Param	Type	Description
path	string	Path to the resource
params	object	Object of query parameters to include in the request

This operation writes the following keys to state:

State Key	Description
data	the resource returned by DHIS2
Example: Get all data values for the 'pBOMPrpg1QX' dataset

get('dataValueSets', {
  dataSet: 'pBOMPrpg1QX',
  orgUnit: 'DiszpKrYNg8',
  period: '201401',
  fields: '*',
});

Example: Get all programs for an organization unit

get('programs', { orgUnit: 'TSyzvBiovKh', fields: '*' });

Example: Get a single tracked entity given the provided ID. See TrackedEntities docs

get('tracker/trackedEntities/F8yKM85NbxW');

---

update

update(resourceType, path, data, [options]) ⇒ Operation

Update a resource object of any type. Updating an object requires all fields of the object you are updating, even if they have not been modified

Param	Type	Description
resourceType	string	The type of resource to be updated. E.g. dataElements, organisationUnits, etc.
path	string	The id or path to the object to be updated. E.g. FTRrcoaog83 or FTRrcoaog83/{collection-name}/{object-id}
data	Object	Data to update. It requires to send the full body. If you want partial updates, use patch operation.
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request.

This operation writes the following keys to state:

State Key	Description
data	the resource returned by DHIS2
Example: a program

update('programs', 'qAZJCrNJK8H', {
  name: '14e1aa02c3f0a31618e096f2c6d03bed',
  shortName: '14e1aa02',
  programType: 'WITHOUT_REGISTRATION',
});

Example: an event

update('events', 'PVqUD2hvU4E', {
  program: 'eBAyeGv0exc',
  orgUnit: 'Ngelehun CHC',
  status: 'COMPLETED',
  storedBy: 'admin',
  dataValues: [],
});

Example: Update a tracker entity. See Update tracker docs

update('trackedEntities', '', {
  createdAt: '2015-08-06T21:12:37.256',
  orgUnit: 'TSyzvBiovKh',
  createdAtClient: '2015-08-06T21:12:37.256',
  trackedEntity: 'IeQfgUtGPq2',
  trackedEntityType: 'nEenWmSyUEp',
  inactive: false,
  deleted: false,
  featureType: 'NONE',
  programOwners: [
    {
      ownerOrgUnit: 'TSyzvBiovKh',
      program: 'IpHINAT79UW',
      trackedEntity: 'IeQfgUtGPq2',
    },
  ],
  attributes: [
    {
      lastUpdated: '2016-01-12T00:00:00.000',
      displayName: 'Last name',
      created: '2016-01-12T00:00:00.000',
      valueType: 'TEXT',
      attribute: 'zDhUuAYrxNC',
      value: 'Russell',
    },
    {
      lastUpdated: '2016-01-12T00:00:00.000',
      code: 'MMD_PER_NAM',
      displayName: 'First name',
      created: '2016-01-12T00:00:00.000',
      valueType: 'TEXT',
      attribute: 'w75KJ2mc4zz',
      value: 'Catherine',
    },
  ],
});

Example: Update a dataSet

update('dataSets', 'lyLU2wR22tC', { name: 'OpenFN Data Set', periodType: 'Weekly' });

Example: a dataSetNotification

update('dataSetNotificationTemplates', 'VbQBwdm1wVP', {
  dataSetNotificationTrigger: 'DATA_SET_COMPLETION',
  notificationRecipient: 'ORGANISATION_UNIT_CONTACT',
  name: 'Notification',
  messageTemplate: 'Hello Updated',
  deliveryChannels: ['SMS'],
  dataSets: [],
});

Example: Update a dataElement

update('dataElements', 'FTRrcoaog83', {
  aggregationType: 'SUM',
  domainType: 'AGGREGATE',
  valueType: 'NUMBER',
  name: 'Paracetamol',
  shortName: 'Para',
});

Example: Update a dataElementGroup

update('dataElementGroups', 'QrprHT61XFk', {
  name: 'Data Element Group 1',
  dataElements: [],
});

Example: Update a dataElementGroupSet

update('dataElementGroupSets', 'VxWloRvAze8', {
  name: 'Data Element Group Set 4',
  dataDimension: true,
  shortName: 'DEGS4',
  dataElementGroups: [],
});

Example: Update a dataValueSet

update('dataValueSets', 'AsQj6cDsUq4', {
  dataElement: 'f7n9E0hX8qk',
  period: '201401',
  orgUnit: 'DiszpKrYNg8',
  value: '12',
});

Example: Update a dataValueSet with related dataValues

update('dataValueSets', 'Ix2HsbDMLea', {
  dataSet: 'pBOMPrpg1QX',
  completeDate: '2014-02-03',
  period: '201401',
  orgUnit: 'DiszpKrYNg8',
  dataValues: [
    {
      dataElement: 'f7n9E0hX8qk',
      value: '1',
    },
    {
      dataElement: 'Ix2HsbDMLea',
      value: '2',
    },
    {
      dataElement: 'eY5ehpbEsB7',
      value: '3',
    },
  ],
});

Example: Update an enrollment given the provided ID

update('enrollments', 'CmsHzercTBa' {
  trackedEntity: 'bmshzEacgxa',
  orgUnit: 'TSyzvBiovKh',
  program: 'gZBxv9Ujxg0',
  enrollmentDate: '2013-10-17',
  incidentDate: '2013-10-17',
});

---

upsert

upsert(resourceType, query, data, [options]) ⇒ Operation

Upsert a record. This will atomically update a record if it already exists, or otherwise create it. This function does not work with the absolute tracker path api/tracker but rather the new tracker paths and deprecated tracker endpoints.

Throws:

• RangeError - Throws range error

Param	Type	Description
resourceType	string	The type of a resource to upsert. E.g. trackedEntities.
query	Object	A query object that allows to uniquely identify the resource to update. If no matches found, then the resource will be created.
data	Object	The data to use for update or create depending on the result of the query.
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
references	An array of all previous data objects used in the Job
Example: Upsert a trackedEntity

upsert('trackedEntities', {}, {
 orgUnit: 'TSyzvBiovKh',
 trackedEntityType: 'nEenWmSyUEp',
 attributes: [
   {
     attribute: 'w75KJ2mc4zz',
     value: 'Qassim',
   },
 ],
});

Example: Upsert a dataElement

upsert(
  'dataElements',
  { filter: 'id:eq:P3jJH5Tu5VC' },
  {
    op: 'add',
    path: '/domainType',
    name: 'Acute',
    shortName: 'AFP follow-up',
    dimensionItemType: 'DATA_ELEMENT',
    legendSets: [],
    aggregationType: 'SUM',
    valueType: 'NUMBER',
    domainType: 'AGGREGATE',
    code: 'DE_359049',
    name: 'Acute Flaccid Paralysis (AFP) follow-up',
   }
 );

---

util

These functions belong to the util namespace.

util.attr

attr(attribute, value) ⇒ object

Converts an attribute ID and value into a DHIS2 attribute object

Param	Type	Description
attribute	string	A tracked entity instance (TEI) attribute ID.
value	string	The value for that attribute.

Example

fn(state => {
   const s = util.attr('w75KJ2mc4zz', 'Elias');
   console.log(s);
   return state;
})

---

util.dv

dv(dataElement, value) ⇒ object

Converts a dataElement and value into a DHIS2 dataValue object

Param	Type	Description
dataElement	string	A data element ID.
value	string	The value for that data element.

Example

fn(state => {
  const s = util.dv('f7n9E0hX8qk', 12);
  console.log(s);
  return state
})

---

util.findAttributeValue

findAttributeValue(trackedEntity, attributeDisplayName) ⇒ string

Gets an attribute value by its case-insensitive display name

Param	Type	Description
trackedEntity	Object	A tracked entity instance (TEI) object
attributeDisplayName	string	The 'displayName' to search for in the TEI's attributes

Example

fn(state => {
   const s = util.findAttributeValue(state.data.trackedEntities[0], 'first name');
   console.log(s);
   return state
})

---

util.findAttributeValueById

findAttributeValueById(trackedEntity, attributeUid) ⇒ string

Gets an attribute value by its uid

Param	Type	Description
trackedEntity	Object	A tracked entity instance (TEI) object
attributeUid	string	The uid to search for in the TEI's attributes

Example

fn(state =>{
  const s = util.findAttributeValueById(state.tei, 'y1w2R6leVmh');
  console.log(s);
  return state
})

---

tracker

These functions belong to the tracker namespace.

tracker.export

export(path, query, [options]) ⇒ Operation

Export data from DHIS2.

Param	Type	Description
path	string	Path to the resource, relative to the /tracker endpoint
query	object	An object of query parameters to be encoded into the URL
[options]	TrackerOptions	An optional object containing parseAs, and apiVersion for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
references	An array of all previous data objects used in the Job
Example: Export a trackedEntity resource using the id

tracker.export('trackedEntities/Gu5UKnIFnJf')

Example: Export all enrollment resources

tracker.export('enrollments', {orgUnit: 'TSyzvBiovKh'});

Example: Export all events

tracker.export('events')

---

tracker.import

import(strategy, payload, [options]) ⇒ Operation

Import data into DHIS2 using the tracker endpoint.

Param	Type	Description
strategy	string	The effect the import should have. Can either be CREATE, UPDATE, CREATE_AND_UPDATE and DELETE.
payload	object	The data to be imported.
[options]	TrackerOptions	An optional object containing parseAs, and apiVersion, and queries for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
references	An array of all previous data objects used in the Job
Example: Import some data and pass the atomicMode parameter

tracker.import('CREATE', $.trackerData, { atomicMode: 'ALL' })

Example: Import a trackedEntity resource

tracker.import(
  'CREATE',
  {
    trackedEntities: [
      {
        orgUnit: 'TSyzvBiovKh',
        trackedEntityType: 'nEenWmSyUEp',
        attributes: [
          {
            attribute: 'w75KJ2mc4zz',
            value: 'Gigiwe',
          },
        ],
      },
    ],
  },
  {
    atomicMode: 'ALL',
  }
);

---

http

These functions belong to the http namespace.

http.get

get(path, [options]) ⇒ Operation

Make a GET request to any DHIS2 endpoint.

Param	Type	Description
path	string	Path to resource.
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the DHIS2 server (excluding the body)
references	An array of all previous data objects used in the Job
Example: Get with query parameters

http.get('dataValueSets', {
 query:{
  dataSet: 'pBOMPrpg1QX',
  orgUnit: 'DiszpKrYNg8',
  period: '201401',
  fields: '*',
}
});

Example: Get an image from a trackedEntityInstance.

http.get('trackedEntityInstances/qHVDKszQmdx/BqaEWTBG3RB/image', {
  headers:{
      Accept: 'image/*'
  },
  parseAs: 'base64',
});

---

http.patch

patch(resourceType, path, data, [options]) ⇒ Operation

Make a PATCH request to any DHIS2 endpoint.

Param	Type	Description
resourceType	string	The type of resource to be updated.
path	string	The id or path to the object to be updated. E.g. FTRrcoaog83 or FTRrcoaog83/{collection-name}/{object-id}
data	Object	Data to update. Include only the fields you want to update. E.g. {name: "New Name"}
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request.

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the DHIS2 server (excluding the body)
references	An array of all previous data objects used in the Job
Example: Update a resource

patch('dataElements', 'FTRrcoaog83', { name: 'New Name' });

---

http.post

post(path, data, [options]) ⇒ Operation

Make a POST request to any DHIS2 endpoint.

Param	Type	Description
path	string	Path to resource.
data	DHIS2Data	Object which defines data that will be used to create a given instance of resource. To create a single instance of a resource, data must be a javascript object, and to create multiple instances of a resources, data must be an array of javascript objects.
[options]	RequestOptions	An optional object containing query, parseAs,and headers for the request.

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the DHIS2 server (excluding the body)
references	An array of all previous data objects used in the Job
Example: Call the tracker endpoint with a JSON payload

http.post("tracker", {
  events: [
    {
      program: "eBAyeGv0exc",
      orgUnit: "DiszpKrYNg8",
      status: "COMPLETED",
    },
  ],
});

---

http.request

request(method, path, [options]) ⇒ Operation

Make a HTTP request to any DHIS2 endpoint

Param	Type	Description
method	string	HTTP method to use
path	string	Path to resource
[options]	RequestOptions	An optional object containing query, requestConfig, and data for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the DHIS2 server (excluding the body)
references	An array of all previous data objects used in the Job
Example: GET request with a URL params

http.request("GET",
  "tracker/relationships", {
   query:{
       trackedEntity: ['F8yKM85NbxW']
   },
});

Example: Upsert a tracker resource

http.request('POST', 'tracker', {
  data: {
  orgUnit: 'TSyzvBiovKh',
  trackedEntityType: 'nEenWmSyUEp',
  attributes: [
    {
      attribute: 'w75KJ2mc4zz',
      value: 'Qassime',
    },
  ],
 },
  query:{
     importStrategy: 'CREATE_AND_UPDATE'
   }
 });

---

Interfaces

RequestOptions

Options object

Properties

Name	Type	Default	Description
query	object		An object of query parameters to be encoded into the URL
headers	object		An object of all request headers
[parseAs]	string	"'json'"	The response format to parse (e.g., 'json', 'text', 'stream', or 'base64'. Defaults to json
[apiVersion]	string	42	The apiVersion of the request. Defaults to 42.

---

RequestOptions

Options object

Properties

Name	Type	Default	Description
query	object		An object of query parameters to be encoded into the URL
headers	object		An object of all request headers
[parseAs]	string	"'json'"	The response format to parse (e.g., 'json', 'text', 'stream', or 'base64'. Defaults to json
[apiVersion]	string	42	The apiVersion of the request. Defaults to 42.

---

TrackerOptions

All options, apart from those listed here, will be appended as query parameters to the URL

Properties

Name	Type	Default	Description
[parseAs]	string	"'json'"	The response format to parse (e.g., 'json', 'text', 'stream', or 'base64'. Defaults to json

---