SHOWOPTIONGROUP rule incorrectly blanks TEI attribute value when option set contains duplicate display names

Support - Assistance technique
1

Component: Tracker / Program Rules / Registration Form

DHIS2 Version: 2.39.8 (may affect other versions)

Description

When a Tracked Entity Instance (TEI) attribute uses an option set that contains multiple options with identical display names (but different UIDs and codes), the program rule engine incorrectly blanks the attribute value after a SHOWOPTIONGROUP action is applied.

Steps to Reproduce

  1. Create an option set containing multiple options with the same display name but different UIDs and codes (e.g., “Ward No-01” appearing multiple times across different administrative units)
  2. Create a SHOWOPTIONGROUP program rule that filters this option set to a specific subset containing one of these duplicate-named options
  3. Open a new TEI enrollment form
  4. Trigger the SHOWOPTIONGROUP rule by setting the condition attribute
  5. Select the option that has duplicate display names from the filtered dropdown

Expected Result

The selected option remains saved in the attribute field.

Actual Result

The field is blanked out with the alert: “[Attribute name] was blanked out because the option ‘[option display name]’ got hidden by your last action.”

Root Cause (identified)

In dhis2.angular.services.js, the function clearAttributeValueForShowHideOptionActions identifies the selected option using:

var selectedOption = optionSet.options.find(function(o) { 
    return o.displayName === value 
});

When duplicate display names exist, this find returns the first matching option in the option set array, which may have a different UID than the one included in the SHOWOPTIONGROUP option group. The subsequent visibility check:

shouldClear = (optionVisibility[attr].showOnly && 
    !optionVisibility[attr].showOnly[selectedOption.id])

fails because the wrong UID is being checked against the visibility map, causing the field to be incorrectly cleared.

Suggested Fix

Match the selected option by code or id rather than displayName:

var selectedOption = optionSet.options.find(function(o) { 
    return o.id === value || o.code === value 
});

Or alternatively ensure the visibility check accounts for all options sharing the same display name rather than stopping at the first match.

Workaround

Ensure all options in the option set have unique display names.

2

Hi Dr. @riaz.somc,

Thanks for the detailed analysis — I was able to understand and reproduce a similar behavior in DHIS2.

The root cause you highlighted makes sense, especially the matching based on displayName, which becomes ambiguous when duplicates exist.

While waiting for a fix, here is a practical workaround process that can help avoid the issue:

Workaround (step-by-step):

  1. Review the option set configuration
  • Identify options with duplicate displayName values
  1. Make display names unique
  • Add context to each option (e.g. location or code)
  • Example:
    • “Ward No-01 (Zone A)”
    • “Ward No-01 (Zone B)”
  1. Keep unique identifiers consistent
  • Ensure each option has a unique code (already recommended best practice)
  1. Update affected program rules (if needed)
  • Re-test SHOWOPTIONGROUP behavior after updating option labels
  1. Validate the fix
  • Reproduce the scenario:
    • Apply rule
    • Select option
    • Confirm the value is no longer cleared

This approach ensures the rule engine can correctly match the selected option and prevents unintended clearing.

That said, I agree this should ideally be handled at engine level (matching by id or code instead of displayName).

Thanks again for sharing this — very insightful :clap:

3

Thanks @riaz.somc for your post and @fidelelukeka for your helpful contributions! :clap:

I have a question please, how does the data entry end user know which “Ward No-01” is which when they’re all duplicates?

I can’t think of a use-case when display name needs to be duplicate because I can’t answer the question to how the datamentry user will be able to differentiate which specific option they’re selecting. For example, they see the option “Ward No-01” and “Ward No-01” how do they know which one is “Zone A” and which one is “Zone B”?

Thanks!

4

Hi
@riaz.somc

It appears that you are using an older version of DHIS2 as well as the deprecated Tracker Capture legacy app. It’s recommended to use the latest supported versions of DHIS2 as well as the Capture app (instead of the Tracker Capture app).

This is handled in a much better and improved way in the newer versions. Is there a reason why you’ve not upgraded? It’s possible to actually start by testing in a test environment before upgrading to get an idea why it’s important to upgrade and experience the improved performance, security, and features.

Thank you!

5

This is a good question. Think of it as dependent dropdowns of location hierarchy where multiple city corporations have “Zone-1”. The data entry operator selects the city corporation first, then moves to select the zone from the next dropdown.

6

We are in the process to move to the capture app. But it needs to re-train the operators accross the country (including public and private sectors). As we have one of the largest national level DHIS2 deployments in the world, it is taking time.

7

Yes, that makes sense now, thanks!

Thanks for the clarification! The good news is that the issue is handled properly in the new app. We have created an entire category with documents and resources to help with the transition. Please feel free to make full use of it… :grin: Implementation - Implémentation > App Transition and Version Upgrades

Thanks!