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
61 changes: 56 additions & 5 deletions docs/reference/effect-badges-legend.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,66 @@
---
title: 'Effect badges legend'
description: 'Lists every effect badge and what its colour and label mean.'
description: 'Lists every effect badge, its icon and colour, the rule action types behind it, and where you see it.'
sidebar_position: 3
---

# Effect badges legend

This page lists every effect badge and what its colour and label mean.
This page lists every kind of rule effect the app shows, with its label, icon and colours. The same colours are used for the badges on fields, the effect badges on rule cards and in the **Trace** tab, the edges in the **Graph** tab, and the rows of the **Server effects** dialog.

:::info Draft
## Where you see effect badges

This page is a stub. The content is coming in a later release of the docs.
- **On a field:** next to the field label. A field shows one badge, for the last rule effect on it in the latest evaluation. Hover over the badge to see the action type and the rule, for example "ASSIGN from rule: PRT-E07 ASSIGN number x 2 to data element". See [Read field badges and hidden-field placeholders](../using-the-app/read-field-badges-and-hidden-field-placeholders.md).
- **On a rule card in the Rules tab:** one badge per action, such as "ASSIGN · Assigned value (number x 2)". See [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md).
- **In the Graph tab:** the toolbar shows the graph legend, limited to the kinds of effect on the current edges. Each edge uses the graph edge colour. See [Map rule dependencies](../using-the-app/map-rule-dependencies.md).

:::
The field badge words (**Hidden**, **Shown**, **Assigned**, ...) are not the same as the graph legend words (**Hide**, **Show**, **Assign**, ...). Both are listed below.

## On-complete badges

**WARNINGONCOMPLETE** and **ERRORONCOMPLETE** use the warning and error colours with a dashed border, and the field badge reads **On complete: warning** or **On complete: error**. The badge shows as soon as the rule fires, not only when you complete the form. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md).

## Legend

The tables below are generated from the app's own legend, so they match what the app shows. The "Meaning" column is the app's description text. Where it says "blocks saving", remember that the playground saves nothing: a rule error blocks saving in a data entry app, and the server reports it during [Verify with server](../using-the-app/check-rules-against-the-server.md).

<!-- generated:start -->

<!-- Generated by scripts/generate-reference.mts from scripts/data/legend.json. Run pnpm generate:reference, do not edit by hand. -->

### In the graph legend

| Graph legend | Field badge | Action types | Icon | Badge colour | Graph edge | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| **Read** | None. Graph edges only. | None. The condition reads the field. | Link | Teal | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#00796b'}}></span> `#00796b` | The rule reads this field in its condition. |
| **Hide** | `HIDEFIELD`, `HIDEOPTION`, `HIDEOPTIONGROUP`: **Hidden**. `HIDESECTION` and `HIDEPROGRAMSTAGE`: none. | `HIDEFIELD`, `HIDEOPTION`, `HIDEOPTIONGROUP`, `HIDESECTION`, `HIDEPROGRAMSTAGE` | Eye, crossed out | Grey | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#494949'}}></span> `#494949` | The rule hides a field, section, option or stage. |
| **Show** | **Shown** | `SHOWFIELD`, `SHOWOPTION`, `SHOWOPTIONGROUP` | Eye | Green | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#388e3c'}}></span> `#388e3c` | The rule shows a field or option. |
| **Assign** | **Assigned** | `ASSIGN` | Pencil | Blue | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#1565c0'}}></span> `#1565c0` | The rule assigns a value to a field. |
| **Required** | **Required by rule** | `SETMANDATORYFIELD`, `UNSETMANDATORYFIELD` | Star | Yellow | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#e56408'}}></span> `#e56408` | The rule makes a field required or optional. |
| **Warning** | `SHOWWARNING`: **Warning**. `WARNINGONCOMPLETE`: **On complete: warning**. | `SHOWWARNING`, `WARNINGONCOMPLETE` | Warning | Yellow | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#ff8302'}}></span> `#ff8302` | The rule shows a warning message. |
| **Error** | `SHOWERROR`: **Error**. `ERRORONCOMPLETE`: **On complete: error**. | `SHOWERROR`, `ERRORONCOMPLETE` | Error | Red | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#c62828'}}></span> `#c62828` | The rule shows an error and blocks saving. |
| **Feedback** | None. Shown in the **Feedback** or **Indicators** card. | `DISPLAYTEXT`, `DISPLAYKEYVALUEPAIR` | Speech bubbles | Purple | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#9c27b0'}}></span> `#9c27b0` | The rule displays text or a key-value pair in the feedback widget. |

### Not in the graph legend

These variants have an icon and colours, but no entry in the legend.

| Variant | Field badge | Action types | Icon | Badge colour | Graph edge |
| --- | --- | --- | --- | --- | --- |
| `message` | None. Shown in the **Server effects** dialog. | `SENDMESSAGE`, `SCHEDULEMESSAGE`, `SCHEDULEEVENT`, `CREATEEVENT` | Envelope | Teal | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#00796b'}}></span> `#00796b` |
| `default` | None. | Any other action type | Info | Grey | <span aria-hidden="true" style={{display: 'inline-block', width: '0.9em', height: '0.9em', borderRadius: '2px', verticalAlign: 'middle', background: '#494949'}}></span> `#494949` |

<!-- generated:end -->

## Notes

- **HIDESECTION** shows no badge. The section shows a placeholder, "Section hidden by" and the rule name, instead.
- **HIDEPROGRAMSTAGE** shows in the **Rules**, **Trace** and **Graph** tabs only. It has no effect on the form or the **Enrollment** rail.
- **UNSETMANDATORYFIELD** shows the **Required by rule** badge, because it changes whether the field is required.

## Related pages

- [Read field badges and hidden-field placeholders](../using-the-app/read-field-badges-and-hidden-field-placeholders.md)
- [Rule action types](./rule-action-types.md)
- [Provenance tags](./provenance-tags.md)
- [Glossary](./glossary.md)
74 changes: 44 additions & 30 deletions docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,7 @@ sidebar_position: 6

# Glossary

Terms are listed in the order you meet them. Entries marked `TODO(verify)` still need to be confirmed against the app.

:::info Draft

Definitions are short on purpose. Fuller explanations will move to the Concepts and Reference pages.

:::
Terms are listed in the order you meet them. Definitions are short on purpose. Follow the links for the full explanation.

## Program rules

Expand All @@ -22,96 +16,116 @@ A DHIS2 metadata rule that checks a condition against the values in a form and r

### rule action

What a program rule does when it runs, for example hiding or showing a field or section, assigning a value, making a field mandatory, or showing a warning, an error, a feedback message or an indicator message.
What a program rule does when it runs, for example hiding or showing a field or section, assigning a value, making a field mandatory, or showing a warning, an error, a feedback message or an indicator message. See [Rule action types](./rule-action-types.md).

### firing

A rule is firing when its condition evaluates to true for the form you have open. The **Rules** tab marks such rules as **Firing** and the others as **Idle**. Firing describes the condition only: actions that run on completion do not take effect until you complete the form.
A rule is firing when it produced at least one effect in the latest evaluation of the form you have open. The **Rules** tab marks such rules as **Firing** and the others as **Idle** or **Out of scope**, and sorts firing rules to the top.

### in scope

A rule that applies to the form you have open. The **Rules** tab can filter to **In scope** rules. `TODO(verify)`: how scope is determined for tracker programs (enrollment form versus stage forms).
A rule that belongs to the form you have open. On the Enrollment form, the rules with no program stage are in scope. On a stage form, the rules of that stage are in scope. In an event program every rule is in scope. In a tracker program, the **Rules** tab has an **In scope** / **All** switch.

### out of scope

A rule that does not apply to the form you have open. The **Rules** tab shows it with an **Out of scope** label. `TODO(verify)`: how scope is determined for tracker programs.
A rule that belongs to another form. The **Rules** tab shows it with an **Out of scope** label and a caption such as "Applies to enrollment". Rules with no program stage also run in stage forms, so they can fire there while still labelled **Out of scope**.

## What you see on a form

### context bar

The bar at the top of the playground, with the **Programs** back link, the program name, **Organisation unit**, the **Event date** or **Enrollment date**, and **Reset playground**. See [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md).

### effect badge

A badge on a field that shows what a rule is doing to it, for example **Hidden**, **Shown**, **Assigned**, **Required by rule**, **Warning**, **Error** or an **On complete** effect.
A badge next to a field label that shows what a rule is doing to the field: **Hidden**, **Shown**, **Assigned**, **Required by rule**, **Warning**, **Error**, **On complete: warning** or **On complete: error**. A field shows one badge, for the last effect on it. See the [Effect badges legend](./effect-badges-legend.md).

### hidden-field placeholder

A dashed placeholder that marks where a rule hid a field ("Hidden by" followed by the rule name) or a section ("Section hidden by" followed by the rule name). The **Show hidden fields** button turns placeholders on and off. It is on when you open a form. When it is off, hidden fields and sections are left out of the form.

### hidden-field placeholders
### Show hidden fields

Dashed placeholders that mark where a rule hid a field or section. Use **Show hidden fields** to turn them on, and each placeholder names the rule that hid it ("Hidden by" followed by the rule name).
The button above the fields that turns hidden-field placeholders on and off. Its label doesn't change: it is teal when on and grey when off.

### Feedback

A card in the sidebar that lists the feedback messages produced by rules that are firing in the form. Each item links to the rule that produced it.
A card in the sidebar that lists the feedback messages produced by firing **DISPLAYTEXT** and **DISPLAYKEYVALUEPAIR** rules. Each item names the action type and the rule that produced it. The items are not links.

### Indicators

A card in the sidebar that lists the indicator values produced by rules that are firing in the form. Each item links to the rule that produced it.
A card in the sidebar that lists the values produced by firing **DISPLAYTEXT** and **DISPLAYKEYVALUEPAIR** rules whose location is the indicators widget. Each item names the action type and the rule that produced it. The items are not links.

### enrollment

In a tracker program, the enrollment of a tracked entity in the program. The app shows it as the **Enrollment** rail that holds the enrollment form and the stage forms, and uses the enrollment date as the date that rules evaluate against.
In a tracker program, the enrollment of a tracked entity in the program. The app shows it as the **Enrollment** rail, which holds the Enrollment form and the stage forms. The **Enrollment date** in the context bar is the enrollment date the rules use. Events in stage forms always use today's date.

### Enrollment form

The rail row that opens the form for the enrollment itself, where you enter tracked entity attributes. Stage forms are listed below it.
The first row of the **Enrollment** rail. It opens the form for the enrollment itself, where you enter tracked entity attributes. The stage forms are listed below it.

## The rules panel

### Rules tab

The rules panel tab that lists the rule catalogue for the program, with a filter for **In scope** or all rules and a status for each rule.
The rules panel tab that lists the program's rules, each with its status (**Firing**, **Idle** or **Out of scope**). In a tracker program, the **In scope** / **All** switch in the panel header chooses which rules it lists.

### Trace tab

The rules panel tab that logs each rule evaluation, so you can see which fields changed and which rules fired.
The rules panel tab that logs each rule evaluation, newest first, with the fields that changed and the rules that fired.

### Graph tab

The rules panel tab that shows a dependency graph of the rules, and can open full screen.
The rules panel tab that shows a dependency graph of the latest evaluation, from fields to rules to the things the rules change. It can open full screen.

## Checking against the server

### Validate form

A form action that checks the form and reports **Form is valid** or **Form has issues**. `TODO(verify)`: what exactly it validates and whether it calls the server.
A form action that checks the values of every field, including fields a rule hid, against the field's metadata (value type, compulsory, options and bounds) in your browser, and reports **Form is valid** or **Form has issues**. It doesn't count rule errors or fields a rule made mandatory, and it doesn't contact the server. See [Validate a form](../using-the-app/validate-a-form.md).

### Verify with server

A form action that sends your input to the server as a dry run and reports whether the server found rule errors or warnings. Nothing is stored.
A form action that sends the form to the server as a dry run and reports whether the server found rule errors, rule warnings or other import errors. Nothing is stored. It is the only form action that needs an organisation unit. See [Check rules against the server](../using-the-app/check-rules-against-the-server.md).

### dry run

A tracker import with `importMode=VALIDATE`. The server checks the payload and discards it, so no data is saved. It is the only write call the app makes.
A tracker import with `importMode=VALIDATE`, sent by **Verify with server**. The server runs its rules and checks the payload, then discards it, so no form data is saved. (Choosing a file in a file or image field is different: it uploads the file to the server straight away.)

### Preview server effects

A form action that opens a read-only summary of what the server would do for your input, such as notifications and scheduled events. It does not post anything.
A form action that opens the **Server effects** dialog for the form as it is. It doesn't send anything. See [Preview server effects](../using-the-app/preview-server-effects.md).

### Preview on-complete effects

The same read-only summary, for the effects of rules that run when you complete the form.
A form action on event forms that runs the completion pass, then opens the **Server effects** dialog for a completed event. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md).

### Server effects dialog

The read-only dialog, titled **Server effects**, that lists the notifications and events the server would create from your rules, and the rule results of the last dry run. Each row has a provenance tag. It has no save button.

### completion pass

The check the app runs when you complete a form. It shows either **Cannot complete this event yet** or **Review before completing**, with **Back to editing** and **Complete anyway** as choices in the review case. `TODO(verify)`: which rules run in a completion pass and when each dialog appears.
The check that **Preview on-complete effects** runs. It sets the form to completed, lets the rules run again, and collects **ERRORONCOMPLETE** errors, empty required fields and **WARNINGONCOMPLETE** warnings. If it finds errors or empty required fields, the banner reads **Cannot complete this event yet** and offers **Back to editing**. If it finds only warnings, it reads **Review before completing** and also offers **Complete anyway**. If it finds nothing, the **Server effects** dialog opens straight away.

## Provenance tags

### provenance tag

The tag on a row of the **Server effects** dialog that says where the row comes from: your browser, the server's dry run, or both. See [Provenance tags](./provenance-tags.md).

### Simulated

A tag on a server effect row that the app worked out itself, rather than one reported by the server. For example, the dry run does not report notifications, so notification rows stay **Simulated**.
The row comes from the rules the app ran in your browser, and there is no server result to compare it with. The dry run doesn't report notifications, so notification rows stay **Simulated**.

### Server-verified

Both your browser and the server's dry run produced the row.

### Server only

A tag on a server effect row that the server reported. `TODO(verify)`: whether this means the app's own evaluation did not produce it.
The server's dry run reported the row, but the app didn't produce it in your browser.

### Not executed by this server

A message on an effect row for an action that the server you are connected to does not run. Some rows add the DHIS2 version that is required, for example "requires 2.43".
A note on a dashed, dimmed row for an action that the server you are connected to doesn't run. Some rows add the version that is required, "Not executed by this server (requires 2.43)".
Loading
Loading