Best practice for changed/revised org units

Good day,

Our instance is being used in a country where the government has completely revised the org unit structure in a region (new place names, groupings, polygons, etc.) and we need to change over to the new org unit structure.

The problem is that all of the “old” org units have tracker data associated with them so the current dashboard has data displaying for the previous org unit structure.

Has anyone experienced a similar situation where the org units changed and what would be the best practice for the transition to the new org unit structure without losing visuals on the dashboard.

Thanks in advance.


Generally these kind of pyramid change should be “thought upfront” and not applied “blindly”

  • trying to preserve the id of the orgunit with data (health center) and
  • update the “polygon/coordinate names” in place if it’s acceptable (if it reflects minor changes)
  • move them around on the new provinces/district/aires/…

Sadly we had this kind of changes too and discovered the day they migrated the dhis2, but it was for an aggregate model.

IMO you’ll need to a matching of the orgunits “new - old” (note this mapping can be stored as a custom attribute if needed for a longer time)

then a migration script either

  • via the api (unsure if you can just update the orgunit of the enrollments and events, or you copy the enrollments/events on the new orgunit, soft delete the one on the “old” orgunit)
  • or via sql (might get tricky if you have duplicated enrollments)

then re run analytics

It looks possible through the UI : Tracker Capture - DHIS2 Documentation

So I would inspect the api calls and automate that transfert of ownership
(perhaps check first the a few records and the results in the dashboard)

Apparently there is an api for that : How to transfer all TEA and program stages from one org. unit to another org. unit in version 2.30 - #11 by Ulanbek

the related documentation Tracker - DHIS2 Documentation

Hi @ACoetzer1988

Before to start TEI/Reports/Dashboard elements I would check first if the old OUs will not be used anymore and there will be no TEIs anymore.
If so, I would just rename those OUs and update polygon datas. This will reduce the number of TEI and other manupilations as will preserve UO’s uid and keep data in “new” renamed OU.
Then you can restructure - move the “new”/renamed OUs under respective parents.

The rest TEIs can be moved manually or by your Postman script.


Dear @Ulanbek and @Stephan_Mestach,

Thank you for the advice and guidance.

I will start with the renaming of the “matched” org units where possible before proceeding with data migration as suggested.

Thank you once again for the links and resources to assist with this.

Kind regards,