From e442be1f91f5f9e7b926f148c366aa7b105c8b17 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Mon, 9 Dec 2024 22:20:13 +0300 Subject: [PATCH 1/2] update readme --- packages/dhis2/README.md | 159 +++++++++++++++++++++------------------ 1 file changed, 86 insertions(+), 73 deletions(-) diff --git a/packages/dhis2/README.md b/packages/dhis2/README.md index 3df96012f..b4ddd3829 100644 --- a/packages/dhis2/README.md +++ b/packages/dhis2/README.md @@ -1,98 +1,107 @@ # Language DHIS2 -An OpenFn language Pack for building expressions and operations for working with -the -[DHIS2 API](http://dhis2.github.io/dhis2-docs/master/en/developer/html/dhis2_developer_manual.html). -Used most commonly via OpenFn.org or by hand with -[OpenFn/core](https://github.com/OpenFn/core) from the root of this repo: +An OpenFn language pack for building expressions and operations to work with the +[DHIS2 API](https://docs.dhis2.org/en/home.html). Commonly used via +[OpenFn.org](https://app.openfn.org) or manually with +[OpenFn CLI](https://github.com/OpenFn/kit). + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Important Note](#important-note) +3. [Configuration](#configuration) +4. [Helper Functions](#helper-functions) +5. [Development](#development) + - [Running Tests](#running-tests) + - [Unit Tests](#unit-tests) + - [Integration Tests](#integration-tests) + - [Troubleshooting Tests](#troubleshooting-tests) + +--- + +## Getting Started + +To use this package, execute commands via OpenFn/core from the root of the +repository: ```sh -core execute \ - -l ../language-dhis2 \ - -e ./tmp/expression.js \ - -s ./tmp/state.json \ - -o ./tmp/output.json +openfn job.js -a dhis2 -s tmp/state.json -o tmp/output.json ``` -> **Important Note:** -> This adaptor uses the old tracker version and is only compatible with DHIS2 -> API versions before 42 (2.42). For later API versions and the new tracker, use -> adaptor 6.0+. See -> [DHIS2 documentation](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html) -> for more information. +For installation and usage, see the +[docs site](https://docs.openfn.org/adaptors/packages/dhis2-docs). -## Documentation +--- -View the [docs site](https://docs.openfn.org/adaptors/packages/dhis2-docs) for -full technical documentation. +## Important Note -There are lots of **examples** for how to use the various helper functions on -the main -[Adaptor docs](https://docs.openfn.org/adaptors/packages/dhis2-docs#modules) -page. +This adaptor supports **old tracker versions** and is compatible with DHIS2 API +versions **prior to 2.42**. +For DHIS2 API versions 2.42+ and the **new tracker**, use **adaptor 6.0+**. +Refer to the +[DHIS2 API documentation](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html) +for details. -### Configuration +--- -View all the required and optional properties for `state.configuration` in the -official -[configuration-schema](https://docs.openfn.org/adaptors/packages/dhis2-configuration-schema/) -definition. +## Configuration -## Development +All required and optional properties for `state.configuration` are defined in +the official +[configuration-schema](https://docs.openfn.org/adaptors/packages/dhis2-configuration-schema/). -Run tests using `pnpm run test` or `pnpm run test:watch`. (NB: that this repo -also contain integration tests which can be run with -`pnpm run integration-test`.) +Ensure you configure: -⚠️ NB: Make changes to the files in `src/` and then use `npm run build` to -generate output files in `lib/`. +- **Username**: DHIS2 admin username +- **Password**: Corresponding DHIS2 admin password +- **Host URL**: URL of the DHIS2 instance -The documentation is autogenerated, so please **rebuild the docs** after making -changes by running `pnpm build docs` +Example configuration: -### Unit Tests +```json +{ + "username": "admin", + "password": "district", + "hostUrl": "https://play.dhis2.org/2.36.6" +} +``` -Unit tests allows to test the functionalities of the adaptor helper functions -such as: +--- -> Does `create('events', payload)` perform a post request to the correct DHIS2 -> API? +## Helper Functions -To run unit tests execute `pnpm run test` (they're the default tests). +Helper functions simplify common DHIS2 operations. View the +[complete function documentation](https://docs.openfn.org/adaptors/packages/dhis2-docs). -Anytime a new functionality is added to the helper functions, more unit tests -needs to be added. +## Development + +### Running Tests + +To run unit and integration tests, use the following commands: + +- **Unit Tests**: `pnpm test` +- **Integration Tests**: `pnpm test:integration` -### End-to-end integration tests +_Note: Integration tests depend on a live DHIS2 instance._ -Integration tests allow us to test the end-to-end behavior of the helper -functions and also to test the examples we provide via inline documentation. +### Unit Tests + +Unit tests validate helper functions independently. For example: -For example with integration tests we answer the following question: +- Does `create('events', payload)` perform a correct POST request? -> Does `create('events', eventPayload)` actually create a new event in a live -> DHIS2 system? +Add new unit tests whenever helper functions are updated. -To run integration tests, execute `npm run integration-test`. These tests use -network I/O and a public connection to a DHIS2 "play" server so their timing and -performance is unpredictable. Consider adding an increased timeout, and -modifying the orgUnit, program, etc., IDs set in `globalState`. +### Integration Tests -#### Troubleshooting the tests +Integration tests validate end-to-end behavior with a live DHIS2 instance. +Ensure your test environment includes: -- Depending on your internet strength please consider changing the **global - timeout** in the `test/mocha.opts` file to avoid faillures related to network - timeouts. +- At least one **organisation unit**. +- One **program** and a corresponding **program stage**. +- A **tracked entity instance** enrolled in the program. -- The behavior of the tests in `test/integration.js` is very unpredictable; they - depend on the **configuration of a target DHIS2 instance**. Currently you need - to have at least one organisation unit with one program, one - trackedEntityInstance and one programStage in it. These components need to be - well configured for the integration tests to work. For example: the - trackedEntityInstance need to be enrolled to the program, which should be - created in that organisation unit and contains at least that programStage. If - the tests fail, you must adjust these attributes in the - [before hook](https://github.com/OpenFn/adaptors/tree/main/packages/dhis2/test/integration.js): +Modify `globalState` in `test/integration.js` as needed: ```javascript before(done => { @@ -111,10 +120,14 @@ before(done => { }); ``` -- Make sure the `update` and `upsert` integration tests don't affect those - initial organisation units, programs, programStage and trackedEntityInstance - required. Otherwise the create integration tests would be broken again; and - that's an endless faillure loop :( +### Troubleshooting Tests + +- **Timeout Errors**: Increase the global timeout in `test/mocha.opts`. +- **Environment Issues**: Ensure DHIS2 components (programs, org units, etc.) + are correctly configured. + +--- -Anytime a new example is added in the documentation of a helper function, a new -integration test should be built. +For further technical details, see the +[documentation](https://docs.openfn.org/adaptors/packages/dhis2-docs) or contact +the [OpenFn community](https://community.openfn.org). From 7d73d2655ea40fc3ed9ee2ebc2a69750f8618be2 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Tue, 10 Dec 2024 15:54:58 +0300 Subject: [PATCH 2/2] update important note and cli command --- packages/dhis2/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/dhis2/README.md b/packages/dhis2/README.md index b4ddd3829..961250d2e 100644 --- a/packages/dhis2/README.md +++ b/packages/dhis2/README.md @@ -25,7 +25,7 @@ To use this package, execute commands via OpenFn/core from the root of the repository: ```sh -openfn job.js -a dhis2 -s tmp/state.json -o tmp/output.json +openfn job.js -a dhis2 -s tmp/state.json ``` For installation and usage, see the @@ -35,12 +35,12 @@ For installation and usage, see the ## Important Note -This adaptor supports **old tracker versions** and is compatible with DHIS2 API -versions **prior to 2.42**. -For DHIS2 API versions 2.42+ and the **new tracker**, use **adaptor 6.0+**. -Refer to the -[DHIS2 API documentation](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html) -for details. +- For DHIS2 API versions 2.42+ and the **new tracker**, use **adaptor 6.0+**. + Refer to the + [DHIS2 API documentation](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html) + 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. ---