[icrc-tafsirdiallo]

Dataset Attribute Options: Organisation Unit Filter Mode

Summary

Add a configurable setting that controls whether a dataset attribute/category option assigned to an organisation unit is available only at that organisation unit or also at its descendants when generating Bulk Load templates.

The setting provides two modes:

• assignedAndDescendants — available at the assigned organisation unit and all descendants. Default.
• assigned — available only at the organisation unit(s) where the category option is directly assigned.

The default behaviour is ancestry-aware and matches how DHIS2 Data Entry resolves category option availability.

Current Status

Currently, Bulk Load uses strict organisation-unit matching when filtering category options.

If a category option is assigned to a parent organisation unit, it is only considered available when generating a template for that exact organisation unit. It is not automatically available for descendant organisation units.

For example:

Country
├── District 1
│   └── Facility 1a
└── District 2

If Partner A is assigned only to Country, the current Bulk Load behaviour is:

Generating for	Current availability
Country	Yes
District 1	No
Facility 1a	No
District 2	No

Scope

Included

• Bulk Load template generation
• Metadata filtering used during template generation
• Template metadata regeneration
• Configuration through application settings

Not Included

This change does not affect:

• Importing a filled-in template
• User permissions
• Dataset organisation-unit assignments
• Category-option organisation-unit assignments
• DHIS2 server-side validation

Import behaviour remains unchanged.

ImportTemplateUseCase only validates that:

1. The row's organisation unit belongs to the dataset.
2. The current user has access to the organisation unit.

It does not re-check whether the attribute option combo is valid for that organisation unit.

Backward Compatibility

The new setting defaults to:

assignedAndDescendants

This preserves the intended ancestry-aware behaviour as the default for existing and new instances.

Administrators who require strict direct-assignment behaviour can explicitly select:

assigned

No migration of existing category-option organisation-unit assignments is required.

Manual Verification

Use the following organisation-unit hierarchy:

Country
├── District 1
│   └── Facility 1a
└── District 2
Country 2

With Partner A assigned only to Country:

1. Verify assignedAndDescendants

1. Select assignedAndDescendants.
2. Generate templates for:
   • Country
   • District 1
   • Facility 1a
   • Country 2
3. Verify that Partner A is available for:
   • Country
   • District 1
   • Facility 1a
4. Verify that Partner A is not available for Country 2.

2. Verify assigned

1. Switch the setting to assigned.
2. Regenerate the templates.
3. Verify that Partner A is available only for Country.
4. Verify that Partner A is not available for District 1 or Facility 1a.

3. Verify direct assignment

1. Assign Partner A directly to Facility 1a.
2. Keep the setting as assigned.
3. Regenerate the template for Facility 1a.
4. Verify that Partner A is now available there.

4. Verify ancestry-aware behaviour is restored

1. Switch back to assignedAndDescendants.
2. Regenerate the templates.
3. Verify that the original ancestry-aware behaviour is restored.

Reviewer Focus

Please verify the following:

• The default mode is assignedAndDescendants.
• The strict assigned mode does not resolve organisation-unit hierarchy paths unnecessarily.
• Existing hierarchy-aware matching remains unchanged.
• The setting is correctly persisted and restored through application settings.
• Template metadata regeneration uses the same setting as normal template generation.
• The setting affects template metadata filtering only.
• Import validation remains unchanged.
• DHIS2 server-side behaviour is unaffected.