Upserting tracked entity instances in DHIS2

OpenFn’s DHIS2 adaptor can now perform upserts!

Lots of DHIS2 users want to “upsert” tracked entity instances, but these external ID upserts aren’t supported by DHIS2’s API. With OpenFn they are.

If you are wondering why upserting is important, pull up a chair for a thread…!


DHIS2 is a system used by health ministries to track and manage critical health data.

“UPSERT” is a portmanteau of the database functions UPDATE and INSERT.

A “tracked entity instance” (TEIs) is anything from a person to a medicine that’s tracked individually.

So, Naledi is a health database admin who is managing 2 different connected systems, let’s call them @openMRS and DHIS2. She would like updates made to a patient named “Jim Smith” (gov ID #123) in OpenMRS also appear in Jim’s (gov ID #123’s) TEI record in DHIS2.

A change is detected in OpenMRS. Should we insert a new record to DHIS2? Should we update an existing record? All we’ve got is a bit of OpenMRS data on Jim & his govt ID #.

UPSERT allows us to update Jim’s record in DHIS2, and to create a new record for him if he doesn’t exist.

In essence, we’ve got to be sure that both systems are talking about the same Jim, even if they’ve got slightly difft data on him. In this example, “gov ID” is the all-important external identifier & it allows us to share the same “Jim” betw different systems with upserts. Yay!

One more thing… upserts cut down on the risk of duplicate data entry and they also allow for transactions to be retried over and over to ensure data integrity. That last bit is called “idempotency” and you can read about it here:

See this OpenFn blog post for more on DHIS2 upserts:

And please don’t hesitate to reach out to one of OpenFn’s implementation specialists if you’d like to have a chat about how upserts can improve your DHIS2 data flows


Nice one. @chaiwa good work here! Excited to see more progress on the overhauled DHIS2 adaptor

1 Like