Dear DHIS2 community,
As part of our ongoing effort to unify program rule evaluation across DHIS2, the web Capture App is now adopting the shared Kotlin-based rule engine already used by the Android App and backend API. This change ensures that program rules behave consistently across web, Android, and server-side environments, making Tracker/Event implementations easier to maintain.
This change could affect your configuration because it removes support for legacy JavaScript-style expressions used in program rules, replacing them with a structured expression parser. Rules that depend on unsupported logic may silently fail or produce incorrect results. The new engine requires expressions to use the supported DHIS2 expression language.
How do I review my configuration?
1. Compile your program rules and Identify unsupported/deprecated logic
Make an inventory of all program rules used in your Tracker or Event programs and identify any logic patterns that use JavaScript-style constructs.
Below is a summary of common JavaScript expressions, with examples of how to rewrite them using supported syntax:
| Logic Area | Previous parser (41 and below) | Kotlin compatible expression | Notes |
|---|---|---|---|
| String concatenation | #{firstName} + ’ ’ + #{lastName} | d2:concatenate(#{firstName}, ’ ', #{lastName}) | + not allowed for concatenating strings |
| Negation | !#{firstName} | #{firstName} == false | JavaScript-style negation is invalid for all value types including booleans |
| Strings in expression box (Assign value) | Hello | “Hello” or ‘Hello’ | Strings must be single or double quoted in the expression box |
| Variable quoting in functions | d2:hasValue(‘firstName’) | d2:hasValue(#{firstName}) | Remove quotes from variables in functions |
2. Update your program rules configuration … if needed
Rewrite any unsupported logic using the supported expression language.
3. Document your changes
Update internal SOPs, configuration guides, and training materials and inform trainers and supervisors of the behavior change.
Testing in your current version
You can toggle the new rule engine on version 41 or 40 (experimental) as long as you have the Capture 101.33.00 or newer version.
To toggle rule engine:
- As system user, open the DataStore Management App
- Click on
capturenamespace - If a Key named
ruleEnginedoes not exist already , create it first by clicking on+ New Keybutton and enteringruleEngineand Add . If it already exists, head to the next step. - Click on key
ruleEngineand on the right hand pane, change the empty{}into{"version" : "new"} - If you want to toggle back to the old rule engine, simply change the above value into
{"version" : "old"}
Useful resources
For more detailed guidance on configuring program rules, supported functions, and migrating to the Kotlin Rule Engine, the following resources may be helpful:
-
DHIS2 Documentation – Program Rule Configuration[1]
Learn how to create, manage, and apply program rules in DHIS2 core.
docs.dhis2.org – Configure Program Rules docs.dhis2.org – Android Program Rules
-
Community of Practice (CoP)
Join the discussion to ask questions, report issues, and share migration tips with other implementers.
DHIS2 Community of Practice
-
Expression Parser and Rule engine gitHub documentation
Expression parser, Rule Engine
We want to hear from you!
We know program rules are used in creative and diverse ways across DHIS2 implementations. Please reply in this thread or add a ticket in Jira if you:
- Have rules that broke or now behave differently
- Encounter issues when testing your programs in version 42
- Are unsure how to rewrite a specific expression
Your feedback helps improve documentation, guides, and support for other implementers going through the same transition.
Thank you for being part of the DHIS2 community and helping make the platform stronger for everyone.
— The DHIS2 Core Team
Both Web and Android work equally now but you can still find the documentation within each of their docs. ↩︎
