@openfn/language-dhis2

Language DHIS2

An OpenFn language pack for building expressions and operations to work with the DHIS2 API. Commonly used via OpenFn.org or manually with OpenFn CLI.

Table of Contents

• Getting Started
• Important Note
• Configuration
• Helper Functions
• Development
  • Running Tests
  • Unit Tests
  • Integration Tests
  • Troubleshooting Tests

Getting Started

To use this package, execute commands via OpenFn/core from the root of the repository:

openfn job.js -a dhis2 -s tmp/state.json

For installation and usage, see the docs site.

Important Note

• For DHIS2 API versions 2.42+ and the new tracker, use adaptor 6.0+. Refer to the DHIS2 API documentation for details.
• For old tracker versions and DHIS2 API versions prior to 2.42, use adaptor 5.0+. But we highly recommend upgrading to the latest version.

Configuration

All required and optional properties for state.configuration are defined in the official configuration-schema.

Ensure you configure:

• Username: DHIS2 admin username
• Password: Corresponding DHIS2 admin password
• Host URL: URL of the DHIS2 instance

Example configuration:

{
  "username": "admin",
  "password": "district",
  "hostUrl": "https://play.dhis2.org/2.36.6"
}

Helper Functions

Helper functions simplify common DHIS2 operations. View the complete function documentation.

Development

Running Tests

To run unit and integration tests, use the following commands:

• Unit Tests: pnpm test
• Integration Tests: pnpm test:integration

Note: Integration tests depend on a live DHIS2 instance.

Unit Tests

Unit tests validate helper functions independently. For example:

• Does create('events', payload) perform a correct POST request?

Add new unit tests whenever helper functions are updated.

Integration Tests

Integration tests validate end-to-end behavior with a live DHIS2 instance. Ensure your test environment includes:

• At least one organisation unit.
• One program and a corresponding program stage.
• A tracked entity instance enrolled in the program.

Modify globalState in test/integration.js as needed:

before(done => {
  fixture.initialState = {
    configuration: {
      username: 'admin',
      password: 'district',
      hostUrl: 'https://play.dhis2.org/2.36.6',
    },
    program: 'IpHINAT79UW',
    orgUnit: 'DiszpKrYNg8',
    trackedEntityInstance: 'uhubxsfLanV',
    programStage: 'eaDHS084uMp',
  };
  done();
});

Troubleshooting Tests

• Timeout Errors: Increase the global timeout in test/mocha.opts.
• Environment Issues: Ensure DHIS2 components (programs, org units, etc.) are correctly configured.

For further technical details, see the documentation or contact the OpenFn community.