Import should have an option to use the optionset 's option name as import value

Implementation - Implémentation
1

When importing values into DHIS2, if the value domain of a data value is controlled by an optionSet and its code has a one-to-one correspondence with its name, why can’t the name be used as the value for import—instead, the code must be used? An import option should be added to avoid the need for applications to perform a lot of tedious code replacement preprocessing.

2

Hi @linxd

Yes, by design the code needs to be used and not the name. One reason could be because code has more restrictions compared to the name. Name is not unique in the system.

Would you please explain further… I assume you mean by ‘applications’ as external apps that use the API to import these dataValues? Is it possible to for these applications to use code by default instead?
Also, in the case you mentioned one-to-one correspondence with the name then wouldn’t you only need to replace the part that indicates it a name to a code?

Thanks!

3

Hi Gassim,

Thanks for your thoughtful response! Let me clarify the points you mentioned:

1. What “applications” refer to

Yes, I’m referring to **external systems** (e.g., hospital information systems, electronic health record tools, or custom data collection apps) that integrate with DHIS2 via its API to import data. These systems often store or display human-readable values (like the `name` in optionSets) because they’re designed for end-users (e.g., clinicians, data entry staff) who recognize “Inpatient” more easily than a code like “IP101”.

2. Why not use `code` by default in these applications?

In theory, applications *could* store and use `code` instead. However, in practice:

  • Many external systems were designed before integrating with DHIS2, and their data models already use `name` (not `code`) for user-friendliness.
  • `code` is often system-specific and less intuitive (e.g., a code like “DX003” doesn’t convey meaning to users, whereas “Diabetes Mellitus” does). Rewriting these systems to use `code` would require significant effort, especially for legacy tools.

3. Even with a 1:1 mapping, why is “replacing name with code” tedious?

While the `code` and `name` have a one-to-one relationship in *our* use case, maintaining this mapping externally creates overhead:

  • Applications must fetch the latest optionSet (via DHIS2’s API) to sync `name`→`code` mappings, which adds network calls and complexity.
  • If an option’s `name` is updated (e.g., due to terminology changes), all external systems must re-sync their mappings to avoid import errors.
  • For large datasets (e.g., monthly reports with thousands of records), batch-replacing `name` with `code` during preprocessing slows down imports and increases the risk of bugs (e.g., typos in mappings).

Why an import option would help

Adding a toggle (e.g., `useOptionName=true` in the API request) would let DHIS2 handle the `name`→`code` conversion internally. This:

  • Reduces integration work for external apps (no need to maintain mappings).
  • Leverages DHIS2’s existing knowledge of optionSets to ensure accuracy (even if `name` changes, DHIS2 can resolve the correct `code`).
  • Preserves backward compatibility (users who prefer `code` can keep using it).

Does this clarify the use case? Happy to discuss further!

Thanks,
Xiaodong Lin

5

When importing values into DHIS2, if the value domain of a data value is controlled by an optionSet and its code has a one-to-one correspondence with its name, why can’t the name be used as the value for import—instead, the code must be used? An import option should be added to avoid the need for applications to perform a lot of tedious code replacement preprocessing.

7

Thank you for the detailed response and explanation. I have done some research about this and will get back to you with what I find; however, I would like to kindly request from you to explain to me which endpoints and API requests are you currently using to retreive the openset code (I know you want it to provide name instead). Would you please share an example of the API requests you are using (POST or GET, which endpoints…etc)?

Also, to confirm the current scenario that you are describing is exactly similar to the scenario below?

I’ll also triage this to the team and see what insights we might get.

Thank you!