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

1. Getting Started
2. Important Note
3. Configuration
4. Helper Functions
5. 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.