`DHIS2` new tracker api

[mtuchi]

Description

Since DHIS2 version 2.36, the tracker API has been re-implemented and the old API endpoints will be removed in v2.42 Learn More here

Tasks

• Re-implement our upsert operation to use the new tracker api
• Maybe use common.http ?
• what else needs to change ?

Demo System We should probably try building this on the latest version like v41.1.0 - see all available demo sites: https://play.dhis2.org/

For all play instances, the username is admin and pw is district

[josephjclark]

Maybe duplicate of https://github.com/OpenFn/adaptors/issues/62

[josephjclark]

We should do a patch on 5.x which enforces api version <41, and has clear documentation.

• the adaptor docs and readme need to clearly state that the adaptor only supports <41 (some functions may work but some will break... the generic http functions should be OK)
• we should log a clear warning if the credential specifies an api version >=42
• If we're really good we'll list the compatible APIs

Then we do 6.x, reworking APIs and removing axios. The 6.x adaptor will only work with DHIS2 >= 38, so again we need to warn in the console if using an old version, and clearly document the compatibility.

So implementations using dhis2 37 would not be able to migrate to adaptor 6.x and use any new features from there. Is that OK? Do we mind?

[aleksa-krolls]

hey @josephjclark @mtuchi I'm going to put @hunterachieng on this this week as we have some community users that are starting to build workflows with our dhis2 adaptor, and I think it's important that they're working with the latest api version.

Re: the question So implementations using dhis2 37 would not be able to migrate to adaptor 6.x and use any new features from there. Is that OK? Do we mind?... I think that is fine. We'll need to document this as a breaking change, but I think many people are migrating to later versions of dhis2 right now.

@hunterachieng I'll book some time to brief you on this in detail, and will ask @daissatou2's support with testing.

[mtuchi]

This issue is a major version bump on dhis2 adaptor, Perhaps @hunterachieng should grab @josephjclark for initial design implementation

[josephjclark]

Ok - maybe we should divide and conquer on this and do the axios work later. That lets us move quickly to support the latest DHIS2 API.

I'll check the API and write up a spec for the minimum work we need to do in the next version.

[aleksa-krolls]

@josephjclark that sounds good - and fyi this is for the Tracker endpoints only (described here)

[josephjclark]

OK @hunterachieng is here the plan.

We need to raise TWO PRs for this.

Patching 5.x

The 5.x version needs patching to make it clear to users that it uses the old tracker API, and some functionality will break in APIv version 42.

So we need to do the following:

• Add a console warning in create/get/update/destroy if the user tries to use API >=42
• Add something to the create/get/update/destroy docs that says: this adaptor uses the old tracker version. For the new one use 6.0
• Update the readme to say this this adaptor uses the old tracker version, for the new one user 6.0

I'll review the wording of the docs but please think carefully about where the documentation needs to be and what information it contains. It should link to DHIS2 docs (see Mtuchi's links above)

This is a PATCH release.

Bumping 6.0

Next we need to create a new 6.0 branch. This will use the new tracker API for the affected resources. The surface API will remain the same.

Please review the example code carefully and make sure that it's still valid. Some options and data structures might change in the new tracker API - refer to the dhis2 migration guide: https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-241/tracker-deprecated.html#webapi_tracker_migration

• The readme needs to say that this adaptor uses the new tracker API introduce in 2.36. We need to point users to the migration guide. Note that many many property names have changed.
• Update the docs for create/get/update/destroy docs to BRIEFLY note that the adaptor uses the new tracker API for trackedEntityInstance, enrollments, events and relationships
• Change all the version warnings you added in the 5.x patch to warn if using an API version <= 2.36. I don't think this will happen but I think it's worth the small change to implement it.
• Update utils/generateUrl() to use the new tracker URLs for the trackedEntityInstance, enrollments, events and relationships resource types.
• The public API should NOT change
• Check the unit tests and see if anything should change. If we do not have tests for the 4 migrated resource types, we must add some to ensure the correct URL is called

To be clear we will NOT remove axios in this release (it has been patched and is more secure than it used to be)

[aleksa-krolls]

@hunterachieng as we discussed, when updating docs and examples in the new version - consider that biggest change is that the new Tracker API no longer supports PUT/update /destroy /delete operations.

Rather, all Tracker creates/updates/deletes are done via a POST /api/tracker request (see docs). Which objects (e.g.,trackedEntities, events) are imported and the importStrategy (e.g., CREATE, UPDATE) are defined by the options and request body payload.

[aleksa-krolls]

Hey @hunterachieng what's left on this issue for this week?

[hunterachieng]

@aleksa-krolls we did the V5 updates now finalising on the major update for v6

[josephjclark]

Hey @aleksa-krolls I just wanna flag that we've done the easier "half" of this issue by putting out a deprecation notice. I've just had a chat with Hunter and we're starting the harder "half". I think it's quite a big and subtle piece of work. I think it'll take a couple of days and has a couple of risks attached.