diff --git a/docs/using-the-app/find-out-why-a-rule-did-or-didnt-fire.md b/docs/using-the-app/find-out-why-a-rule-did-or-didnt-fire.md index 5ae29b6..47eb2d9 100644 --- a/docs/using-the-app/find-out-why-a-rule-did-or-didnt-fire.md +++ b/docs/using-the-app/find-out-why-a-rule-did-or-didnt-fire.md @@ -1,15 +1,74 @@ --- title: 'Find out why a rule did or didn''t fire' -description: 'Shows how to use the Rules and Trace tabs to see why a rule fired or stayed idle.' +description: 'Shows how to use the Rules and Trace tabs of the rules panel to see which rules are firing, which are idle or out of scope, and what each evaluation changed.' sidebar_position: 5 --- # Find out why a rule did or didn't fire -This page shows how to use the **Rules** and **Trace** tabs to see why a rule fired or stayed idle. +## Goal -:::info Draft +Find a rule, check whether it is firing for the values in the form, and follow the evaluations that made it fire or stop firing. -This page is a stub. The content is coming in a later release of the docs. +## Before you start -::: +- You have a program open in the playground. See [Find and open a program](./find-and-open-a-program.md). +- The rules panel is on the right of each form. It has three tabs: **Rules**, **Trace** and **Graph**. It opens on **Rules**. + +## Steps + +### Check the rule's status on the Rules tab + +1. Select the **Rules** tab. The header shows how many rules are in scope and how many are firing, for example "16 in scope · 3 firing". +2. In a tracker program, choose which rules to list with the switch in the header: + - **In scope** (the default) lists only the rules that belong to the form you have open. + - **All** lists every rule in the program. + + Event programs have no switch. All their rules are in scope. +3. Find your rule. Rules are sorted by priority, with the firing rules moved to the top. The list reorders as rules start and stop firing. +4. Read the status at the top of the card: + - **Firing**: the rule produced at least one effect in the latest evaluation. + - **Idle**: the rule is in scope, but its condition did not produce an effect in the latest evaluation. + - **Out of scope**: the rule belongs to another form. The card says which one, for example "Applies to enrollment" or "Applies to PRT Follow-up". +5. Compare the condition shown on the card with the values in the form. Each card shows: + - The rule name. + - One badge per action, with the action type and its target, for example "HIDEFIELD · Hide target field". When the action has data, the badge adds it after an equals sign. For display actions, the target is the location and the detail is the static text. + - The condition, as it is written in the rule. +6. To see the full rule, select the **Program rule details** button (the info icon) on the card. See [Open and edit a rule](./open-and-edit-a-rule.md). + +![Rules panel on the Rules tab, with firing rules sorted to the top](./img/rules-tab.png) + +### Follow the evaluations on the Trace tab + +1. Change a value in the form. +2. Select the **Trace** tab. Each rule evaluation adds an entry at the top, even when no rule fired. The newest entry opens by itself the first time. +3. Read the entry header: when the evaluation happened, for example "just now" or "2m ago", and how many rules fired. An entry with no changed field is tagged **Initial**. The first one is the evaluation that ran when the form loaded. In the stage and event forms of a tracker program, a change in another form also adds an **Initial** entry, because the form evaluates its rules again with the new values. +4. Select the expand button on an entry to see its details, and select it again to collapse it. A collapsed entry shows the number of effects. +5. In the expanded entry, read: + - **Changed fields**: the fields whose change caused this evaluation. This includes fields that a rule assigned a new value to: an **ASSIGN** action that changes a value causes another evaluation, and that entry lists the assigned field. + - **Rules fired**: each rule that fired, with its effect, the target and the data. If no rule fired, the entry says "No rules fired". + +![Rules panel on the Trace tab, listing rule evaluations](./img/trace-tab.png) + +## What you'll see + +A rule that never shows up as **Firing**, and never appears in the **Trace** tab, did not produce an effect. Check its condition against the values you entered, and check that the program rule variables it uses read the fields you expect. The [Program rule details](./open-and-edit-a-rule.md) dialog lists the variables in the condition. + +A rule only appears in the **Trace** tab in the evaluations where it fired. Before the first evaluation is recorded, the tab shows "No rules observed yet". It keeps the latest 200 evaluations. + +Selecting a card on the **Rules** tab, or a rule in a **Trace** entry, highlights that rule and opens the **Graph** tab. Selecting a **Trace** entry shows that evaluation in the graph. A banner at the top of the **Trace** and **Graph** tabs shows what is highlighted, for example "Highlighting evaluation 2m ago" or "Rule:" followed by the rule name. Select **Clear** to remove the highlight. See [Map rule dependencies](./map-rule-dependencies.md). + +If the **Rules** tab shows "No program rules match this view.", there are no rules for the form you have open. In a tracker program, switch to **All**. + +### Out of scope rules in tracker stage forms + +In a tracker program, a rule is in scope when its program stage matches the form you have open. Rules without a program stage are in scope in the **Enrollment form** only. + +A rule without a program stage still runs in stage forms, and can fire there. On the **Rules** tab of a stage form it is labelled **Out of scope**, even when it fires, and it is not counted in the "firing" number in the header. Its effects still show on the form and in the **Trace** tab. + +## Related pages + +- [How program rules are evaluated](../concepts/how-program-rules-are-evaluated.md) +- [Map rule dependencies](./map-rule-dependencies.md) +- [Open and edit a rule](./open-and-edit-a-rule.md) +- [Work with repeatable stages](./work-with-repeatable-stages.md) diff --git a/docs/using-the-app/map-rule-dependencies.md b/docs/using-the-app/map-rule-dependencies.md index 1424080..70ed654 100644 --- a/docs/using-the-app/map-rule-dependencies.md +++ b/docs/using-the-app/map-rule-dependencies.md @@ -1,15 +1,69 @@ --- title: 'Map rule dependencies' -description: 'Shows how to use the Graph tab to see which rules depend on which fields and variables.' +description: 'Shows how to use the Graph tab to see which field changes led to which rules, and what each rule did to fields, sections and feedback.' sidebar_position: 6 --- # Map rule dependencies -This page shows how to use the **Graph** tab to see which rules depend on which fields and variables. +## Goal -:::info Draft +See one rule evaluation as a graph: the fields you changed, the rules that fired, and the fields, sections and feedback items those rules affected. Use it to follow a chain of rules, for example an assignment that makes another rule fire. -This page is a stub. The content is coming in a later release of the docs. +## Before you start -::: +- You have a program open in the playground. See [Find and open a program](./find-and-open-a-program.md). +- You have changed at least one value in the form. The graph only shows rules that fired. + +## Steps + +1. In the rules panel next to the form, select the **Graph** tab. It shows the latest evaluation. +2. To look at an earlier evaluation, select an entry in the **Trace** tab, then go back to **Graph**. To highlight one rule, select its card on the **Rules** tab or its name in a **Trace** entry. Both open the **Graph** tab. See [Find out why a rule did or didn't fire](./find-out-why-a-rule-did-or-didnt-fire.md). +3. Read the graph from left to right: field, then rule, then target. +4. Hover an edge to see its label if it isn't shown. +5. Use the zoom controls to zoom in and out. You can drag nodes to tidy the layout. +6. To see a large graph better, select the **Open graph in full screen** button (the full-screen icon) in the graph toolbar. The graph opens in a dialog titled **Rule dependency graph**. If you highlighted an evaluation or a rule, the dialog shows it under the title. Close the dialog to go back to the panel. + +![Rules panel on the Graph tab, with the full-screen button](./img/graph-tab.png) + +![Rule dependency graph opened in full screen](./img/graph-full-screen.png) + +## What you'll see + +### Nodes + +The toolbar shows a colour swatch for each kind of node, and the number of nodes and edges, for example "6 nodes · 5 edges". + +| Node | What it is | +| --- | --- | +| **Field** | A data element or attribute. It is either a field you changed in this evaluation or a field a rule acted on. A field node shows the field's current value, when it has one. | +| **Rule** | A program rule that fired in this evaluation. | +| **Section** | A section that a rule hid. | +| **Feedback** | A **Feedback** or **Indicators** item that a rule displayed. The node is labelled with the location and the item's static text, for example "indicators:Calculated double" or "feedback:Trigger text is:". | + +### Edges + +- An edge from a field to a rule is a read edge. It links the fields that changed in this evaluation to each rule that fired. If you changed a field and no rule fired, the graph shows only that field. +- An edge from a rule to a target is an effect edge. Its label and colour show the kind of effect, for example hide, assign or warning. + +The read edge links every changed field to every rule that fired, whether or not the rule's condition uses that field. The changed fields include fields that a rule assigned. When an **ASSIGN** action changes a value, the form evaluates its rules again, and the graph of that evaluation shows the assigned field, for example **Assigned value (number x 2)**, as the only source field, linked to every rule that fired. To see which fields a rule actually reads, open its details and look at **Variables referenced**. See [Open and edit a rule](./open-and-edit-a-rule.md). + +When the graph has more than four edges, the read edge labels are hidden. Hover an edge to show its label. + +The toolbar also has a legend that lists the effect kinds that appear on the edges in the current graph, for example **Read**, **Hide**, **Assign** or **Required**. For the colours and icons, see the [Effect badges legend](../reference/effect-badges-legend.md). + +### The empty graph + +When the evaluation has nothing to show, for example right after the form loads with no rule firing, the **Graph** tab shows: + +> **No rule relationships yet** +> +> Interact with the form to build the dependency graph. Only rules active in the latest evaluation are shown. Select a trace entry to inspect a past evaluation. Connections flow Field → Rule → Target (read / effect). + +The full-screen button only appears when the graph has nodes. + +## Related pages + +- [Find out why a rule did or didn't fire](./find-out-why-a-rule-did-or-didnt-fire.md) +- [Effect badges legend](../reference/effect-badges-legend.md) +- [How program rules are evaluated](../concepts/how-program-rules-are-evaluated.md) diff --git a/docs/using-the-app/open-and-edit-a-rule.md b/docs/using-the-app/open-and-edit-a-rule.md index e4c8060..e8a4463 100644 --- a/docs/using-the-app/open-and-edit-a-rule.md +++ b/docs/using-the-app/open-and-edit-a-rule.md @@ -1,15 +1,109 @@ --- title: 'Open and edit a rule' -description: 'Shows how to open a rule from the playground and edit it in the Maintenance app or Metadata Management.' +description: 'Shows how to read a program rule in the Program rule details dialog and open it for editing in the Maintenance app or Metadata Management.' sidebar_position: 7 --- # Open and edit a rule -This page shows how to open a rule from the playground and edit it in the Maintenance app or Metadata Management. +## Goal -:::info Draft +Read the whole of a program rule, including its condition in plain language and every action, without leaving the playground. When you find a problem, open the rule in the DHIS2 app where you edit rules. -This page is a stub. The content is coming in a later release of the docs. +## Before you start + +- You have a program open in the playground. See [Find and open a program](./find-and-open-a-program.md). +- To edit the rule, you need access to the rule editor app and the authorities to change program rules. See [Who can edit](#who-can-edit) below. + +## Steps + +1. In the rules panel, select the **Rules** tab and find the rule. +2. Select the **Program rule details** button (the info icon) on the rule card. You can also select a rule name in the **Server effects** dialog. See [Preview server effects](./preview-server-effects.md). +3. Read the dialog. Its sections are described below. +4. To change the rule, select **Edit in Maintenance app** or **Edit in Metadata Management app** at the bottom of the dialog. The rule opens in a new tab. +5. Select **Close** to go back to the form. + +![Program rule details dialog for an ASSIGN rule](./img/rule-details.png) + +## What you'll see + +### Header + +The header shows "Program rule", the rule name, its status (**Firing**, **Idle** or **Out of scope**) and the rule description, if it has one. When you open the dialog from the **Server effects** dialog, the status is always **Firing**. + +### Basic details + +| Item | What it shows | +| --- | --- | +| **Name** | The rule name. | +| **Code** | The rule code. | +| **Identifier** | The rule ID. | +| **Program** | The program the rule belongs to. | +| **Program stage** | The stage the rule is limited to. A rule with no stage shows "All stages (enrollment)", in event programs too. | +| **Priority** | The rule priority. | +| **Actions** | The number of actions, for example "2 action(s)". | +| **Last updated** | The date and time of the last change, and who made it. | + +A value that isn't set shows a dash. + +### Condition + +The **Condition** section shows the condition expression as it is written in the rule. + +Under it, the app asks your DHIS2 server for a plain-language reading of the condition. While it waits, you see "Generating a plain-language description…". The reading then appears in a **Description** box. Fetching it saves nothing. + +If the reading can't be loaded, a yellow warning starts with "Could not describe this expression:". It is followed by the reason the server gave, or by "Could not load a plain-language description for this condition. The raw expression is shown above." The condition expression is still shown. + +**Variables referenced** lists each variable and function in the condition as a chip, with its kind: + +- `#{...}`: **Data element** +- `A{...}`: **Tracked entity attribute** +- `V{...}`: **Environment variable** +- `d2:` functions: **Function** + +Program rule variables are shown by name. When you open the dialog from the **Server effects** dialog, the chips show the raw expressions. + +### Actions + +One card per action, numbered **Action 1**, **Action 2** and so on, with the action type. Each card can show: + +- The target, with its kind and ID, for example a **Data element**, **Tracked entity attribute**, **Program stage section**, **Program stage**, **Option** or **Option group**. +- **Data (expression)**: the expression the action evaluates. +- **Content (static text)**: the static text, for display actions. +- **Location**: where a display action shows its text. + +If the rule can't be loaded, the dialog shows "Could not load this rule:" followed by the reason. + +### The edit link + +The dialog is a read-only view. The link at the bottom opens the rule in the app that edits program rules on your DHIS2 version. + +:::note + +On DHIS2 2.40 to 2.42, the link reads **Edit in Maintenance app** and opens the rule in the Maintenance app. On DHIS2 2.43, it reads **Edit in Metadata Management app** and opens the rule in Metadata Management. ::: + +The app picks the link from the version your DHIS2 server reports. If it can't tell the version, it uses the Maintenance app link. + +After you save a change in the other app, reload the playground page so it loads the changed rule. + +### Who can edit + +Anyone who can open the program can open the details dialog. No extra authority is needed. + +To use the edit link, you need: + +| DHIS2 version | To open the editor app | To edit the rule | +| --- | --- | --- | +| 2.40 to 2.42 | `M_dhis-web-maintenance` | `F_PROGRAM_RULE_ADD`, and `F_PROGRAM_RULE_DELETE` to delete rules, plus metadata write sharing on the program | +| 2.43 | `M_dhis-web-metadata-management` | The same as for 2.40 to 2.42 | + +Without access to the editor app, the link opens a DHIS2 page that says "Unable to find an app for this URL." These authorities were checked on DHIS2 2.43 only. See [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md). + +## Related pages + +- [Find out why a rule did or didn't fire](./find-out-why-a-rule-did-or-didnt-fire.md) +- [Rule action types](../reference/rule-action-types.md) +- [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md) +- [DHIS2 version compatibility](../introduction/dhis2-version-compatibility.md)