Updating DHIS2 metadata value types

Sometimes it is required to update the value type of a data element, tracked entity attribute or option set in DHIS2, however if you have tried this yourself you may have noticed that this field is greyed out in the maintenance app.

This is for good reason, because the value type can cause problems if changed. For example imagine a field which was originally value type TEXT. As the system is used, lots of data values are entered against this field and stored in the system. If the value was to be updated to type NUMBER for example, suddenly all the text values previously entered are invalid and cannot be rendered in the data entry tools!

There are safe value types to change to based on the current ones though. In general, moving to less specific data types (eg number → text) is OK, but the reverse is not. This is because a number, 12.45 for example, can also be written as text. But the the text ‘Hello’ cannot be written as a number.

If you do want to change a value type in the safe direction there’s a two main ways:

Without using terminal or curl

  1. Find the uids for each metadata item you want to update
  2. For each metadata type, create an api request to get the information on the fields
  3. For example if you wanted to update the value types for three data elements with UIDS: JmZ0m8Q3gwh,qxWAgIAfZAh and y57kkdyw35d you would do the following:
  4. https://play.dhis2.org/2.37.3/api/29/dataElements.json?fields=:owner&filter=id:in:[JmZ0m8Q3gwh,qxWAgIAfZAh,y57kkdyw35d]
    1. To modify this for your own needs, replace the UIDs in between the square brackets [ ] with the UIDs for the elements you want to update and modify the base url to the server you are using.
    2. For updating other metadata types, replace dataElements with the metadata type you are trying to update, for example optionSets or trackedEntityAttributes
  5. Download this file using File → Save in your browser
  6. Modify the value types to the desired value types
  7. Import the file in the import export app (metadata import module)

Using curl

  1. Find the uids for each metadata item you want to update
  2. Send a curl request to update the value type for each UID, eg: java curl --user admin:district -X PATCH "https://play.dhis2.org/2.37.3/api/dataElements/JuTpJ2Ywq5b" -H 'Content-Type: application/json' -d '{"valueType": "INTEGER"}'
  3. Where admin:district are a valid username:password combination for the server you are updating and https://play.dhis2.org/2.37.3 is replaced with the base url of the server you are updating

After either of these methods, check the value type has updated correctly in the maintenance app (clear cache may be required)

Finally if there any existing values in the system, check that these are still being displayed both in the relevant data entry application and in the analytics apps (after analytics has run).