dhis2@3.2.6

Functions

execute(operations) ⇒ Operation

Execute a sequence of operations. Wraps language-common/execute, and prepends initial state for DHIS2.

configMigrationHelper(state) ⇒ object

Migrates apiUrl to hostUrl if hostUrl is blank. For OpenFn.org users with the old-style configuration.

create(resourceType, data, [options], [callback]) ⇒ Operation

Create a record

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

Update data. A generic helper function to update a resource object of any type. Updating an object requires to send all required fields or the full body

get(resourceType, query, [options], [callback]) ⇒ Operation

Get data. Generic helper method for getting data of any kind from DHIS2.

This can be used to get DataValueSets,events,trackedEntityInstances,etc.

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

Upsert a record. A generic helper function used to atomically either insert a row, or on the basis of the row already existing, UPDATE that existing row instead.

discover(httpMethod, endpoint) ⇒ Operation

Discover DHIS2 api endpoint query parameters and allowed operators for a given resource's endpoint.

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

Patch a record. A generic helper function to send partial updates on one or more object properties.

You are not required to send the full body of object properties.
This is useful for cases where you don't want or need to update all properties on a object.

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

Delete a record. A generic helper function to delete an object

findAttributeValue(trackedEntityInstance, attributeDisplayName) ⇒ string

Gets an attribute value by its case-insensitive display name

attr(attribute, value) ⇒ object

Converts an attribute ID and value into a DSHI2 attribute object

dv(dataElement, value) ⇒ object

Converts a dataElement and value into a DSHI2 dataValue object

request(configuration, axiosRequest) ⇒ Promise

The request client takes configuration from state and an axios request object then (1) logs the method and URL, (2) applies standard headers and auth before spreading the rest of the axios configuration, and (3) executes an axios request.

selectId(resourceType) ⇒ string

Determines the attribute name for a DHIS2 system ID given a resource type.

execute(operations) ⇒ `Operation`

Execute a sequence of operations. Wraps language-common/execute, and prepends initial state for DHIS2.

Kind: global function

Param	Type	Description
operations	`Operations`	Operations to be performed.

Example

execute(
  create('foo'),
  delete('bar')
)(state)

configMigrationHelper(state) ⇒ `object`

Migrates apiUrl to hostUrl if hostUrl is blank. For OpenFn.org users with the old-style configuration.

Kind: global function

Param	Type	Description
state	`object`	the runtime state

Example

configMigrationHelper(state)

create(resourceType, data, [options], [callback]) ⇒ `Operation`

Create a record

Kind: global function
Access: public

Param	Type	Description
resourceType	`string`	Type of resource to create. E.g. `trackedEntityInstances`, `programs`, `events`, ...
data	`Object`	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]	`Object`	Optional `options` to define URL parameters via params (E.g. `filter`, `dimension` and other import parameters), request config (E.g. `auth`) and the DHIS2 apiVersion.
[callback]	`function`	Optional callback to handle the response

Example (a program)

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

Example (an event)

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

Example (a trackedEntityInstance)

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

Example (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 (a dataElement)

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

Example (a dataElementGroup)

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

Example (a dataElementGroupSet)

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

Example (a dataValueSet)

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

Example (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 (an enrollment)

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

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

Update data. A generic helper function to update a resource object of any type. Updating an object requires to send all required fields or the full body

Kind: global function
Access: public

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 `all required fields` or the `full body`. If you want `partial updates`, use `patch` operation.
[options]	`Object`	Optional `options` to define URL parameters via params (E.g. `filter`, `dimension` and other import parameters), request config (E.g. `auth`) and the DHIS2 apiVersion.
[callback]	`function`	Optional callback to handle the response

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 (a trackedEntityInstance)

update('trackedEntityInstances', 'IeQfgUtGPq2', {
  created: '2015-08-06T21:12:37.256',
  orgUnit: 'TSyzvBiovKh',
  createdAtClient: '2015-08-06T21:12:37.256',
  trackedEntityInstance: 'IeQfgUtGPq2',
  lastUpdated: '2015-08-06T21:12:37.257',
  trackedEntityType: 'nEenWmSyUEp',
  inactive: false,
  deleted: false,
  featureType: 'NONE',
  programOwners: [
    {
      ownerOrgUnit: 'TSyzvBiovKh',
      program: 'IpHINAT79UW',
      trackedEntityInstance: 'IeQfgUtGPq2',
    },
  ],
  enrollments: [],
  relationships: [],
  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 (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 (a dataElement)

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

Example (a dataElementGroup)

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

Example (a dataElementGroupSet)

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

Example (a dataValueSet)

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

Example (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 (a single enrollment)

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

get(resourceType, query, [options], [callback]) ⇒ `Operation`

Get data. Generic helper method for getting data of any kind from DHIS2.

This can be used to get DataValueSets,events,trackedEntityInstances,etc.

Kind: global function
Returns: Operation - state
Access: public

Param	Type	Description
resourceType	`string`	The type of resource to get(use its `plural` name). E.g. `dataElements`, `trackedEntityInstances`,`organisationUnits`, etc.
query	`Object`	A query object that will limit what resources are retrieved when converted into request params.
[options]	`Object`	Optional `options` to define URL parameters via params beyond filters, request configuration (e.g. `auth`) and DHIS2 api version to use.
[callback]	`function`	Optional callback to handle the response

Example (all data values for the 'pBOMPrpg1QX' dataset)

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

Example (all programs for an organization unit)

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

Example (a single tracked entity instance by a unique external ID)

get('trackedEntityInstances', {
  ou: 'DiszpKrYNg8',
  filter: ['flGbXLXCrEo:Eq:124', 'w75KJ2mc4zz:Eq:John'],
});

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

Upsert a record. A generic helper function used to atomically either insert a row, or on the basis of the row already existing, UPDATE that existing row instead.

Kind: global function
Throws:

RangeError - Throws range error

Access: public

Param	Type	Description
resourceType	`string`	The type of a resource to `upsert`. E.g. `trackedEntityInstances`
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]	`Object`	Optional configuration that will be applied to both the `get` and the `create` or `update` operations.
[callback]	`function`	Optional callback to handle the response

Example (Example `expression.js` of upsert)

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

discover(httpMethod, endpoint) ⇒ `Operation`

Discover DHIS2 api endpoint query parameters and allowed operators for a given resource's endpoint.

Kind: global function
Access: public

Param	Type	Description
httpMethod	`string`	The HTTP to inspect parameter usage for a given endpoint, e.g., `get`, `post`,`put`,`patch`,`delete`
endpoint	`string`	The path for a given endpoint. E.g. `/trackedEntityInstances` or `/dataValueSets`

Example (a list of parameters allowed on a given endpoint for specific http method)

discover('post', '/trackedEntityInstances')

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

Patch a record. A generic helper function to send partial updates on one or more object properties.

You are not required to send the full body of object properties.
This is useful for cases where you don't want or need to update all properties on a object.

Kind: global function
Access: public

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. Include only the fields you want to update. E.g. `{name: "New Name"}`
[options]	`Object`	Optional configuration, including params for the update ({preheatCache: true, strategy: 'UPDATE', mergeMode: 'REPLACE'}). Defaults to `{operationName: 'patch', apiVersion: state.configuration.apiVersion, responseType: 'json'}`
[callback]	`function`	Optional callback to handle the response

Example (a dataElement)

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

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

Delete a record. A generic helper function to delete an object

Kind: global function
Access: public

Param	Type	Description
resourceType	`string`	The type of resource to be deleted. E.g. `trackedEntityInstances`, `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]	`Object`	Optional `options` for `del` operation including params e.g. `{preheatCache: true, strategy: 'UPDATE', mergeMode: 'REPLACE'}`. Run `discover` or see DHIS2 documentation. Defaults to `{operationName: 'delete', apiVersion: state.configuration.apiVersion, responseType: 'json'}`
[callback]	`function`	Optional callback to handle the response

Example (a tracked entity instance)

destroy('trackedEntityInstances', 'LcRd6Nyaq7T');

findAttributeValue(trackedEntityInstance, attributeDisplayName) ⇒ `string`

Gets an attribute value by its case-insensitive display name

Kind: global function
Access: public

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

Example

findAttributeValue(state.data.trackedEntityInstances[0], 'first name')

attr(attribute, value) ⇒ `object`

Converts an attribute ID and value into a DSHI2 attribute object

Kind: global function
Access: public

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

Example

attr('w75KJ2mc4zz', 'Elias')

dv(dataElement, value) ⇒ `object`

Converts a dataElement and value into a DSHI2 dataValue object

Kind: global function
Access: public

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

Example

dv('f7n9E0hX8qk', 12)

request(configuration, axiosRequest) ⇒ `Promise`

Kind: global function
Returns: Promise - a promise that will resolve to either a response object or an error object.

Param	Type	Description
configuration	`object`	configuration must have a username and password
axiosRequest	`object`	the axiosRequest contains valid axios params: https://axios-http.com/docs/req_config

selectId(resourceType) ⇒ `string`

Determines the attribute name for a DHIS2 system ID given a resource type.

Kind: global function

Param	Type
resourceType	`string`

Functions​

execute(operations) ⇒ Operation​

configMigrationHelper(state) ⇒ object​

create(resourceType, data, [options], [callback]) ⇒ Operation​

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

get(resourceType, query, [options], [callback]) ⇒ Operation​

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

discover(httpMethod, endpoint) ⇒ Operation​

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

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

findAttributeValue(trackedEntityInstance, attributeDisplayName) ⇒ string​

attr(attribute, value) ⇒ object​

dv(dataElement, value) ⇒ object​

request(configuration, axiosRequest) ⇒ Promise​

selectId(resourceType) ⇒ string​

Functions

execute(operations) ⇒ `Operation`

configMigrationHelper(state) ⇒ `object`

create(resourceType, data, [options], [callback]) ⇒ `Operation`

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

get(resourceType, query, [options], [callback]) ⇒ `Operation`

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

discover(httpMethod, endpoint) ⇒ `Operation`

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

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

findAttributeValue(trackedEntityInstance, attributeDisplayName) ⇒ `string`

attr(attribute, value) ⇒ `object`

dv(dataElement, value) ⇒ `object`

request(configuration, axiosRequest) ⇒ `Promise`

selectId(resourceType) ⇒ `string`