feat: [DHIS2-20429][DHIS2-20530] use configured TEA Search Operators in the Search forms #4413

simonadomnisoru · 2025-12-02T08:34:11Z

DHIS2-20429 and DHIS2-20530

Tech summary:

use the configured TEA Search Operators in the Search forms (the regular search page and the 2 relationships search forms)
- for all three search forms, unify the logic for determining search operators in getSearchOperator.ts and convert the form values into server filters in searchFormToServer.ts
The fallback search bug was also fixed in this PR DHIS2-20530

The search operator is computed like this:

1) Value types that always use EQ
The following value types will ignore preferredSearchOperator and always use the EQ operator: BOOLEAN, TRUE_ONLY, AGE, ORGANISATION_UNIT, USERNAME, Unique TEAs, and TEAs with option sets (except MULTI_TEXT).

2) Value types that currently use a from–to range
These will ignore preferredSearchOperator and continue using GE and LE. The following value types fall into this category: NUMBER, INTEGER, INTEGER_POSITIVE, INTEGER_NEGATIVE, INTEGER_ZERO_OR_POSITIVE, DATE, DATETIME, and TIME.

3) Value types that currently use LIKE
These will start using the preferredSearchOperator metadata. If preferredSearchOperator is not defined, they will fall back to the first available operator in [LIKE, SW, EQ] that is not listed in blockedSearchOperators. The following value types fall into this category: TEXT, LONG_TEXT, EMAIL, PHONE_NUMBER, and PERCENTAGE.

4) MULTI_TEXT value type
It will ignore preferredSearchOperator and fall back to the first available operator in [LIKE, SW, EQ] that is not listed in blockedSearchOperators.

github-actions · 2025-12-02T08:41:27Z

🚀 Deployed on https://deploy-preview-4413.capture.netlify.dhis2.org

...es/capture-core/metaDataStoreLoaders/programs/quickStoreOperations/storeProgramIndicators.ts

JoakimSM

Looks like a good start @simonadomnisoru

JoakimSM · 2025-12-02T14:36:48Z

src/core_modules/capture-core/metaData/DataElement/DataElement.ts

+    set preferredSearchOperator(preferredSearchOperator: string | undefined) {
+        this._preferredSearchOperator = preferredSearchOperator;
+    }
+    get preferredSearchOperator(): string | undefined {
+        return this._preferredSearchOperator;
+    }
+
+    set blockedSearchOperators(blockedSearchOperators: Array<string> | undefined) {
+        this._blockedSearchOperators = blockedSearchOperators;
+    }
+    get blockedSearchOperators(): Array<string> | undefined {
+        return this._blockedSearchOperators;
+    }


Do we need these new properties on the DataElement class here, or is the searchOperator enough?

Great question, I have the same doubt. I think searchOperator will be enough. I'll remove the other two. Thank you for the feedback!

henrikmv

Nice work, Simona! I did an initial review and left some comments. Thank you!

src/core_modules/capture-core/components/FormFields/New/HOC/messages/withSearchHelpMessage.tsx

...taDataMemoryStoreBuilders/common/factory/searchGroup/searchOperator/forcedSearchOperators.ts

henrikmv · 2025-12-16T20:52:32Z

src/core_modules/capture-core/components/FormFields/New/HOC/messages/withSearchHelpMessage.tsx

+                        {helpText} <br />
+                    </div>


I’d recommend not showing the help text for TEAs with optionSet configured or value types Yes/No and Yes Only, as users can only select from predefined options and the help text doesn’t add value - just extra noise in the form. WDYT?

Great suggestion @henrikmv,

I agree that the help text below Yes/No (BOOLEAN) and Yes Only (TRUE_ONLY) doesn’t add much value.

I’ve removed it, which makes the form cleaner 👍

On the other hand, for the help text below the optionSet, I do think it adds value. Option sets behave differently for the MULTI_TEXT value type (the preferredSearchOperator is applied in this case). Since users are not aware of this difference and all optionSet use the same dropdown selector, I think it could be confusing to show the help text only for some dropdowns. WDYT?

Thanks!

Thanks for the insight @simonadomnisoru. I am a bit concerned whether the preferredSearchOperator should be applied to MULTI_TEXT option sets.

For MULTI_TEXT option sets, searches can only be performed using a single value, and the order of the values being searched through is not taken into account. As a result, the selected preferred search operator does not influence the search outcome; the behaviour remains the same regardless of the operator chosen.

WDYT?

This goes a bit beyond the MULTI_TEXT discussion, but I wanted to share something for consideration.

It seems to me that preferredSearchOperator may not have a practical impact for some value types. For example:

AGE — always matched on an exact date

MULTI_TEXT — always matched on full value

USERNAME — always matched on the full username

ORGANISATION_UNIT — always matched on the full organisation unit name

In addition, I’m not entirely sure why PERCENTAGE is not handled as a range-based value type? Not related to your changes, but related to the feature itself.

From my perspective, preferredSearchOperator seems useful for value types that are not range-based, and where search can be performed on partial values:

TEXT

LONG_TEXT

EMAIL

PHONE_NUMBER

I would be really happy to be corrected if I’m missing something here - I just wanted to raise this as a point for discussion.

Hi @ameenhere, what do you think about the concerns raised by @henrikmv? I’ll summarize below what we agreed to implement in the first iteration of the search improvement initiative:

Value types that currently use EQ will ignore the preferredSearchOperator and continue to use EQ. These are:

BOOLEAN

TRUE_ONLY

AGE

Value types that currently use the To-From range will ignore the preferredSearchOperator and continue to use GE and LE. These are:

NUMBER

INTEGER

INTEGER_POSITIVE

INTEGER_NEGATIVE

INTEGER_ZERO_OR_POSITIVE

DATE

DATETIME

TIME

Value types that currently use LIKE will start using the preferredSearchOperator instead. These are:

TEXT

LONG_TEXT

EMAIL

PHONE_NUMBER

PERCENTAGE

MULTI_TEXT

ORGANISATION_UNIT

USERNAME

The main point of the first iteration of search improvements was simply to offer an alternative to LIKE for the value types mentioned in point 3. It’s now up to the implementer/admin to decide which preferredSearchOperator has a practical impact for those value types. Does it make sense, in this first iteration, to further reduce the list to only the value types mentioned by @henrikmv: TEXT, LONG_TEXT, EMAIL, and PHONE_NUMBER?

@henrikmv Regarding PERCENTAGE, I don't know why isn’t handled as a range-based value type. If we want to change that, it sounds like a separate ticket to me
Thanks!

Thanks @simonadomnisoru

I think documenting the fallback cases is also a good addition. We will also need to document this behaviour for the end user somewhere as well.

If LIKE is blocked for MULTI_TEXT, wouldnt Capture "fallback" to SW or EQ like others?

@ameenhere

I documented the fallback cases in Confluence too. Sure, the feature will have its behavior documented for the end user in the Capture app docs

Yes, it could fall back to SW or EQ like the others, but above you mentioned that "LIKE is the only operator usable for a MULTI_TEXT value type". So if that is the case, I’m confused why we would allow it to be blocked if it is the only one that works

Ah. To clarify, the operation will go through with SW and EQ as well. The results will not be what we expect it to be.

Anyway.. let us move that to a separate ticket (either BE, or FE change, or both).

But we can go ahead with the changes in this PR 👍

Hey @simonadomnisoru ! I played around a bit with the changes on Friday, and I think I agree with @henrikmv even more in terms of the help text.

In the Capture UI, for username, orgUnit and optionset, we always show a drop down. Meaning there is no possibility in the Capture UI to for user to type a partial text for a username or orgunit or any optionset. So that already gives an impression that the search is going to be attempted with an exact match.

However on discussing with you, I understand that Capture is using LIKE operator, even though the UI feels like it is using an exact match.

So my thinking currently is
For OrgUnit and Username valueType. We switch to EQ and ignore the preferredSearchOperator. (Similar to OptionSet)
In addition to the above, we do not show any help text for these valueTypes, since the UI already indicates it is a direct match by selecting an option. Wdyt @simonadomnisoru ?

Sounds good to me, thank you for your input @ameenhere. I’ve updated the code to ignore preferredSearchOperator for USERNAME and ORGANISATION_UNIT. I’ve also documented our latest agreements on how Capture computes the search operator for each Value type in Confluence.

I created a bug for the MULTI_TEXT issue -> https://dhis2.atlassian.net/browse/DHIS2-20694

Let me know if it looks good now @henrikmv and @ameenhere

sonarqubecloud · 2025-12-22T10:37:11Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
8.6% Duplication on New Code

See analysis details on SonarQube Cloud

feat: use configured TEA Search Operators in the Search page

20554e5

simonadomnisoru added the preview label Dec 2, 2025

Merge branch 'master' into DHIS2-20429

8c887b1

simonadomnisoru added preview and removed preview labels Dec 2, 2025

simonadomnisoru added the e2e-tests label Dec 2, 2025

feat: use configured TEA Search Operators in the Search page

9145bfa

simonadomnisoru added preview and removed preview labels Dec 2, 2025

simonadomnisoru commented Dec 2, 2025

View reviewed changes

...es/capture-core/metaDataStoreLoaders/programs/quickStoreOperations/storeProgramIndicators.ts Outdated Show resolved Hide resolved

JoakimSM reviewed Dec 2, 2025

View reviewed changes

Merge branch 'master' into DHIS2-20429

f9b2f05

simonadomnisoru added preview and removed preview e2e-tests labels Dec 3, 2025

simonadomnisoru added 5 commits December 8, 2025 16:30

chore: add convertSearchFormToServer converter

36794f4

Merge branch 'master' into DHIS2-20429

91b00ed

Merge branch 'master' into DHIS2-20429

8ca911b

feat: apply convertSearchFormToServer to relationship search

31fd281

feat: apply convertSearchFormToServer to relationship search

36fc648

simonadomnisoru marked this pull request as ready for review December 15, 2025 15:04

simonadomnisoru requested a review from a team as a code owner December 15, 2025 15:04

simonadomnisoru removed the preview label Dec 15, 2025

simonadomnisoru requested a review from JoakimSM December 15, 2025 15:07

simonadomnisoru added the preview label Dec 16, 2025

simonadomnisoru changed the title ~~feat: [DHIS2-20429] use configured TEA Search Operators in the Search forms~~ feat: [DHIS2-20429][DHIS2-20530] use configured TEA Search Operators in the Search forms Dec 16, 2025

simonadomnisoru added 2 commits December 16, 2025 12:43

fix: use formValues to build fallbackFormValues

69899f8

chore: sonarcube errors

574122e

henrikmv reviewed Dec 16, 2025

View reviewed changes

simonadomnisoru added 3 commits December 17, 2025 09:35

chore: remove withSearchHelpMessage

831467a

chore: remove withSearchHelpMessage

b3a8fa4

chore: clean translations

3627913

simonadomnisoru requested a review from henrikmv December 17, 2025 08:42

chore: ignore preferredSearchOperator and force LIKE for MULTI_TEXT

63339a0

simonadomnisoru requested a review from ameenhere December 18, 2025 11:17

chore: use defaultSearchOperators fallback for forcedSearchOperators too

73104b6

simonadomnisoru added preview and removed preview labels Dec 18, 2025

feat: ignore preferredSearchOperator for username and orgunit

4cee065

simonadomnisoru added preview and removed preview labels Dec 22, 2025

feat: [DHIS2-20429][DHIS2-20530] use configured TEA Search Operators in the Search forms #4413

Are you sure you want to change the base?

feat: [DHIS2-20429][DHIS2-20530] use configured TEA Search Operators in the Search forms #4413

Uh oh!

Conversation

simonadomnisoru commented Dec 2, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tech summary:

The search operator is computed like this:

Uh oh!

github-actions bot commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

JoakimSM left a comment

Choose a reason for hiding this comment

Uh oh!

JoakimSM Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

henrikmv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

henrikmv Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

henrikmv Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

henrikmv Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ameenhere Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ameenhere Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

ameenhere Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Dec 22, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

simonadomnisoru commented Dec 2, 2025 •

edited by atlassian bot

Loading

github-actions bot commented Dec 2, 2025 •

edited

Loading

JoakimSM Dec 2, 2025 •

edited

Loading

henrikmv Dec 16, 2025 •

edited

Loading

simonadomnisoru Dec 18, 2025 •

edited

Loading

simonadomnisoru Dec 18, 2025 •

edited

Loading

simonadomnisoru Dec 22, 2025 •

edited

Loading