dhis2 update readme

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
 ```
 
-> **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.
+- 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.
 
-### 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).