Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 71 additions & 5 deletions docs/concepts/how-program-rules-are-evaluated.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,81 @@
---
title: 'How program rules are evaluated'
description: 'Explains how the client rule engine and the server importer each evaluate program rules.'
description: 'Explains how the rule engine in your browser and the DHIS2 tracker importer each evaluate program rules, and when each one runs.'
sidebar_position: 1
---

# How program rules are evaluated

This page explains how the client rule engine and the server importer each evaluate program rules.
## The short version

:::info Draft
Program rules run in two places. The rule engine in your browser evaluates them every time a value in the form changes, and shows the result on the fields, in the sidebar and in the rules panel. The DHIS2 server evaluates them again in its tracker importer, which the app only reaches through **Verify with server**, a dry run that saves nothing.

This page is a stub. The content is coming in a later release of the docs.
## How it works

:::
### In the browser

The app runs the DHIS2 rule engine (`@dhis2/rule-engine`) in your browser, through the `dhis2-form-utils` libraries. Each form has its own engine.

The engine evaluates the rules:

- Once when the form opens. The **Trace** tab shows this evaluation with the **Initial** tag, which marks any evaluation with no changed field.
- After every value change in the form. Changes are grouped: the engine waits about 40 ms after the last change, then evaluates once with all the fields that changed.
- After an **ASSIGN** action changes a value. The app writes the assigned value into the field, and that change causes another evaluation. Its **Trace** entry lists the assigned field under **Changed fields**.
- When the organisation unit or the date in the context bar changes, because both are passed to the form as values.
- In a tracker program, when a value changes in another form of the same enrollment. Each form shares its values with the other forms about 150 ms after you stop typing, and the forms that receive them evaluate their rules again. The **Trace** tab records this re-evaluation with the **Initial** tag, because no field changed in the form itself. If an **ASSIGN** action then changes a value, a second entry that names the assigned field follows.

Which rules each form evaluates:

- An event program form, or a stage form in a tracker program, evaluates the rules that have no program stage, plus the rules of its own stage.
- The **Enrollment form** evaluates only the rules that have no program stage.

The engine returns a list of effects. The app applies them right away:

- Field effects (hide, show, assign, mandatory, warning, error, options) change the field and add an effect badge.
- **HIDESECTION** effects replace the section body with a hidden-field placeholder.
- **DISPLAYTEXT** and **DISPLAYKEYVALUEPAIR** effects go to the **Feedback** and **Indicators** sidebar.
- Every evaluation is added to the **Trace** tab, and the latest one drives the **Rules** tab statuses and the **Graph** tab.
- Actions that only the server performs (**SENDMESSAGE**, **SCHEDULEMESSAGE**, **SCHEDULEEVENT**, **CREATEEVENT**) are not executed. They appear in the trace and in the **Server effects** dialog as simulated rows.

```mermaid
flowchart LR
A[You change a value] --> B[Rule engine in the browser evaluates the rules]
B --> C[Fields: badges, hidden-field placeholders, warnings and errors]
B --> D[Sidebar: Feedback and Indicators]
B --> E[Rules panel: Rules, Trace and Graph]
```

**Preview on-complete effects** runs one extra pass, the completion pass. The app sets the form status to `COMPLETED`, waits for the engine to evaluate again, and lists the on-complete warnings, errors and empty required fields it finds. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md).

### On the server

The DHIS2 server evaluates program rules in its tracker importer when data is imported. The app never imports data. **Verify with server** sends the form to `POST /api/tracker?importMode=VALIDATE&async=false`. With `importMode=VALIDATE` the importer runs its validation and its program rules, reports what it found, and saves nothing.

The app then reads the report:

- Errors and warnings that a program rule produced are matched to the rule. Errors on a field that is on screen are shown on that field.
- Anything else is listed in the notice above the form buttons, and other import errors are listed under **Other import errors**.
- The server results also feed the **Server effects** dialog, where rows the browser and the server both produced are tagged **Server-verified** and rows only the server reported are tagged **Server only**.

```mermaid
flowchart LR
A[You select Verify with server] --> B[Dry run: POST /api/tracker with importMode=VALIDATE]
B --> C[Server runs its program rules and validation]
C --> D[Results: errors on fields, notice above the buttons, Server effects dialog]
```

Only **Verify with server** contacts the importer, and it is the only action that needs an organisation unit. **Validate form**, **Preview server effects** and **Preview on-complete effects** work in the browser only.

## Why it matters

- What you see while you type is the browser engine's result. It is fast and covers every rule, but it is not the server's answer.
- **Verify with server** is how you check that the server agrees. The two can disagree, for reasons explained in [Why client and server results differ](./why-client-and-server-results-differ.md).
- Because the engine runs on every change, the **Trace** tab can show you the exact change that made a rule fire or stop firing.

## Related pages

- [Rule inputs](./rule-inputs.md)
- [Why client and server results differ](./why-client-and-server-results-differ.md)
- [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md)
- [Check rules against the server](../using-the-app/check-rules-against-the-server.md)
- [Is it safe on production?](../introduction/is-it-safe-on-production.md)
79 changes: 74 additions & 5 deletions docs/concepts/rule-inputs.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,84 @@
---
title: 'Rule inputs'
description: 'Explains the inputs a rule can read: enrollment, events, user groups and roles, and option groups.'
description: 'Explains what the app gives the rule engine to evaluate: form values, values from other forms of the enrollment, user groups and roles, option groups, constants, the organisation unit, dates and the event status.'
sidebar_position: 2
---

# Rule inputs

This page explains the inputs a rule can read: enrollment, events, user groups and roles, and option groups.
## The short version

:::info Draft
A program rule can only react to what the rule engine is given. The app gives it the values in the form you have open, and in a tracker program also the values from the enrollment and from the other stage forms. It adds your user groups and roles, the program's constants, the selected organisation unit, the dates from the context bar and the event status. If a rule depends on something that is not in this list, it evaluates as if that value were empty.

This page is a stub. The content is coming in a later release of the docs.
## How it works

:::
### Values in the form

Every field in the form you have open is an input, whether you typed the value or a rule assigned it. The engine evaluates again after each change, see [How program rules are evaluated](./how-program-rules-are-evaluated.md).

### Values from other forms (tracker programs)

In a tracker program all forms of the enrollment stay open in the background, so the values you entered in one form are available to the rules in the others:

- A stage form receives the values of the **Enrollment form** as the enrollment, so rules that read tracked entity attributes (`A{...}`) work in stage forms.
- A stage form also receives the values of every other stage form and event in the rail as the enrollment's other events. Its own values are not repeated in that list. This is what feeds program rule variables with the source types `DATAELEMENT_PREVIOUS_EVENT`, `DATAELEMENT_NEWEST_EVENT_PROGRAM` and `DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE`.
- The **Enrollment form** receives the values of all stage forms and events as the enrollment's events.

Values from other forms arrive about 150 ms after you stop typing. Every non-repeatable stage in the rail, and every event you add to a repeatable stage with **Add event**, counts as an event as soon as it exists, even if you have not entered anything in it yet.

```mermaid
flowchart LR
E[Enrollment form] -- attributes as the enrollment --> S1[Stage form]
S2[Other stage forms and events] -- values as other events --> S1
S1 -- values as events --> E
```

### User groups and roles

When a program opens, the app reads your user groups and user roles from `/api/me` and passes their IDs to the engine. Rules that use `d2:inUserGroup` or `d2:hasUserRole` evaluate against your own account, not against the users who enter data in production. Test with an account that has the groups or roles you want to check.

The app does not pass organisation unit group memberships, so `d2:inOrgUnitGroup` has nothing to match against and always returns false in the app.

### Option groups

If a rule action uses **HIDEOPTIONGROUP** or **SHOWOPTIONGROUP**, the app fetches those option groups from `/api/optionGroups` to know which options they contain. If you cannot read an option group, those actions are expected to hide or show nothing, without a message. `TODO(verify)`: this case has not been tested.

### Constants

The app loads every constant in the instance (`/api/constants`, ID and value) and passes them to the engine, so `C{...}` in a condition or expression resolves.

### Organisation unit

The organisation unit you select in the context bar is the event's organisation unit, and in a tracker program the enrollment's. Until you select one, the engine evaluates without an organisation unit. Its code is not passed, so `V{orgunit_code}` is empty.

### Dates

| Form | Date the engine uses |
| --- | --- |
| Event program form | The **Event date** from the context bar, as the event date. |
| **Enrollment form** | The **Enrollment date** from the context bar, as the enrollment date. The incident date is the **Incident date** field when the program shows one, otherwise the enrollment date. |
| Tracker stage form or event | Today. Each event gets today's date when it is first shown and keeps it, and stage forms have no date field. |

Because all events in a tracker program share today's date, rules that compare events by date, such as rules on the previous event, depend on an order the app does not control.

### Event status

The event you have open has the status `ACTIVE`. **Preview on-complete effects** sets it to `COMPLETED` for the completion pass, so the engine evaluates the on-complete rules, and **Back to editing** or closing the **Server effects** dialog sets it back to `ACTIVE`. The other events of an enrollment are always `ACTIVE`, and the enrollment itself is always active.

### What the server receives

**Verify with server** sends a different set of inputs: the payload a save would send, without the values of fields a rule hid. See [Why client and server results differ](./why-client-and-server-results-differ.md).

## Why it matters

- When a rule does not fire, check its inputs first. The **Trace** tab shows which fields changed in each evaluation, and the rule details show the variables the condition reads.
- To test a rule that reads values from another stage, enter those values in the other stage form first, then come back.
- To test rules on user groups or roles, log in as a user who has them.

## Related pages

- [How program rules are evaluated](./how-program-rules-are-evaluated.md)
- [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md)
- [Work with repeatable stages](../using-the-app/work-with-repeatable-stages.md)
- [Test on-complete rules](../using-the-app/test-on-complete-rules.md)
- [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md)
75 changes: 71 additions & 4 deletions docs/concepts/why-client-and-server-results-differ.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,82 @@
---
title: 'Why client and server results differ'
description: 'Explains why the app and the DHIS2 server can report different results for the same input.'
description: 'Explains why the rule engine in your browser and the DHIS2 server can report different results for the same form.'
sidebar_position: 3
---

# Why client and server results differ

This page explains why the app and the DHIS2 server can report different results for the same input.
## The short version

:::info Draft
The browser and the server run program rules separately, and they do not always see the same thing. Some actions only the server can perform, some only run on newer DHIS2 versions, the dry run does not report notifications, and **Verify with server** sends the server a narrower set of inputs than the browser engine uses. When the results differ, it is usually one of these reasons, not a broken rule.

This page is a stub. The content is coming in a later release of the docs.
## How it works

### Actions only the server runs

The browser engine does not execute **SENDMESSAGE**, **SCHEDULEMESSAGE**, **SCHEDULEEVENT** or **CREATEEVENT**. When one of these rules fires, the app records the effect in the trace and shows it in the **Server effects** dialog, but nothing is sent or created. Open the dialog with **Preview server effects** or **Preview on-complete effects** to see what the server would do.

The other way round, the server can report a rule effect the browser did not produce. The **Server effects** dialog tags such a row **Server only**.

### Version gates

The server only executes an action type if your DHIS2 version supports it. The app reads the version of the instance and compares:

| Action type | Executed by the server |
| --- | --- |
| **SENDMESSAGE**, **SCHEDULEMESSAGE**, **ASSIGN**, **SETMANDATORYFIELD**, **SHOWERROR**, **SHOWWARNING**, **ERRORONCOMPLETE**, **WARNINGONCOMPLETE** | From DHIS2 2.40 |
| **SCHEDULEEVENT** | From DHIS2 2.43 |
| **CREATEEVENT** | Not executed |

In the **Server effects** dialog, a row for an action your server does not execute is dashed and dimmed, with the note "Not executed by this server (requires 2.43)" or "Not executed by this server". The row is there for reference only.

:::note

If the app cannot read the server version, it treats the server as DHIS2 2.40.

:::

### Notifications stay Simulated

The dry run does not report notifications. **SENDMESSAGE** and **SCHEDULEMESSAGE** rows in the **Server effects** dialog keep the **Simulated** tag even after **Verify with server**, and the dialog footer says so. A **Simulated** notification row means the browser engine fired the rule. It does not confirm that the server would send the message.

Rule errors and warnings, mandatory fields and assignments do come back from the dry run. When the browser and the server both produced the same effect for the same rule, the row is tagged **Server-verified**. See the [provenance tags](../reference/provenance-tags.md).

### Different inputs

**Verify with server** sends exactly what a save would send. That is not the same as what the browser engine evaluates:

- **Values of hidden fields are left out.** The payload drops the values of fields a rule hid, and empty values. A server rule that reads a hidden field does not see its value.
- **A stage form sends its event on its own.** In a tracker program, verifying a stage form sends that one event, without its enrollment, tracked entity or the other events. In the browser the same form sees the enrollment's attributes and the other events. The server can also reject the bare event with errors that are not about rules, listed under **Other import errors**. `TODO(verify)`: the exact server response for a stage event sent this way.
- **The Enrollment form sends no events.** Verifying the **Enrollment form** sends the tracked entity and its enrollment only. The server sees no event values in this case.
- **Stage events are dated today.** Every event in a tracker program gets today's date, whatever the **Enrollment date** in the context bar says. Rules that use event dates, or that compare one event with the previous one, can behave differently from real data entry.
- **Your account is the user.** In the browser, rules on user groups or roles evaluate against the account you are logged in with. In a dry run, DHIS2 is expected to evaluate them against the importing user, which is the same account. This has not been checked.

See [Rule inputs](./rule-inputs.md) for the full list of what the browser engine uses.

### "Out of scope" rules that still fire

This difference is inside the browser, but it often looks like a mismatch. In a tracker program, a rule with no program stage is evaluated in every stage form, and it can fire there. The **Rules** tab of a stage form still labels it **Out of scope**, because its scope is the enrollment, and the "firing" count in the panel header leaves it out. Switch the panel to **All** to see it, and check the field badges and the **Trace** tab for its effects.

```mermaid
flowchart TB
A[Same form values] --> B[Browser engine: all values, enrollment and other events]
A --> C[Dry run payload: hidden values dropped, one event or one enrollment]
B --> D[Effects on the form and Simulated rows]
C --> E[Server report: Server-verified and Server only rows]
```

## Why it matters

- Treat the browser result as the answer to "what does this rule do with these values". Treat **Verify with server** as the answer to "would the server accept this payload".
- When a row says **Server only**, the server evaluated something the browser did not. Check the inputs above before you change the rule.
- When a notification or scheduled event matters, check its row in the **Server effects** dialog and remember that the dry run cannot confirm it.

## Related pages

- [How program rules are evaluated](./how-program-rules-are-evaluated.md)
- [Rule inputs](./rule-inputs.md)
- [Check rules against the server](../using-the-app/check-rules-against-the-server.md)
- [Preview server effects](../using-the-app/preview-server-effects.md)
- [Provenance tags](../reference/provenance-tags.md)
- [DHIS2 version compatibility](../introduction/dhis2-version-compatibility.md)
Loading
Loading