diff --git a/docs/reference/effect-badges-legend.md b/docs/reference/effect-badges-legend.md index e49636f..1519d8e 100644 --- a/docs/reference/effect-badges-legend.md +++ b/docs/reference/effect-badges-legend.md @@ -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). + + + + + +### 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 | `#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 | `#494949` | The rule hides a field, section, option or stage. | +| **Show** | **Shown** | `SHOWFIELD`, `SHOWOPTION`, `SHOWOPTIONGROUP` | Eye | Green | `#388e3c` | The rule shows a field or option. | +| **Assign** | **Assigned** | `ASSIGN` | Pencil | Blue | `#1565c0` | The rule assigns a value to a field. | +| **Required** | **Required by rule** | `SETMANDATORYFIELD`, `UNSETMANDATORYFIELD` | Star | Yellow | `#e56408` | The rule makes a field required or optional. | +| **Warning** | `SHOWWARNING`: **Warning**. `WARNINGONCOMPLETE`: **On complete: warning**. | `SHOWWARNING`, `WARNINGONCOMPLETE` | Warning | Yellow | `#ff8302` | The rule shows a warning message. | +| **Error** | `SHOWERROR`: **Error**. `ERRORONCOMPLETE`: **On complete: error**. | `SHOWERROR`, `ERRORONCOMPLETE` | Error | Red | `#c62828` | The rule shows an error and blocks saving. | +| **Feedback** | None. Shown in the **Feedback** or **Indicators** card. | `DISPLAYTEXT`, `DISPLAYKEYVALUEPAIR` | Speech bubbles | Purple | `#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 | `#00796b` | +| `default` | None. | Any other action type | Info | Grey | `#494949` | + + + +## 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) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c76e529..84215dd 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -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 @@ -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)". diff --git a/docs/reference/messages-and-errors.md b/docs/reference/messages-and-errors.md index 0d80dd2..7e57489 100644 --- a/docs/reference/messages-and-errors.md +++ b/docs/reference/messages-and-errors.md @@ -1,15 +1,400 @@ --- title: 'Messages and errors' -description: 'Lists the messages and errors the app shows, with what each means and what to do.' +description: 'Lists the errors, warnings, empty states and key notices the app shows, grouped by screen, with what each means and what to do.' sidebar_position: 5 --- # Messages and errors -This page lists the messages and errors the app shows, with what each means and what to do. +This page lists the messages the app shows, grouped by screen. Each entry gives the text exactly as the app shows it, where it appears, what it means and what to do. "Kind" is **Error**, **Warning**, **Empty** (nothing to show yet) or **Info**. -:::info Draft +Messages that contain a value the app fills in are shown in code formatting, where `{rule}`, `{stage}`, `{n}` and similar stand for that value. For problems with access and setup, also see [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). -This page is a stub. The content is coming in a later release of the docs. +Some messages say "save". The playground saves no form data: **Verify with server** is a dry run. The wording comes from the app. -::: +## Program list + +### "No programs found. Try adjusting your search or filter." + +- **Kind:** Empty +- **Where you see it:** in the program table. +- **What it means:** no program you can read matches the search term and the **All** / **Tracker** / **Event** switch. +- **What to do:** clear the search or choose **All**. If a program you expect is still missing, you may not have metadata read access to it. See [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +### "Error" / "Error loading programs" + +- **Kind:** Error +- **Where you see it:** a notice above the program table. +- **What it means:** the request for the program list failed. +- **What to do:** reload the page and check that you are still logged in to DHIS2. + +## Opening a program + +### "Program not found" + +- **Kind:** Error +- **Where you see it:** a notice titled "Error", with a **Back to programs** link, instead of the playground. +- **What it means:** the program doesn't exist, or you don't have metadata read access to it. +- **What to do:** select **Back to programs** and open the program from the list. See [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +### "Could not load this program. Try again later." + +- **Kind:** Error +- **Where you see it:** a notice titled "Error", instead of the playground. +- **What it means:** the program metadata request failed for another reason, such as a network or server error. +- **What to do:** reload the page. If it keeps happening, [report a bug](../help/report-a-bug.md). + +### "No organisation units available" + +- **Kind:** Info +- **Where you see it:** under the context bar. The forms are not shown. The body reads "This program has no organisation units assigned, or none are accessible to the current user." +- **What it means:** the program has no organisation units assigned. +- **What to do:** assign at least one organisation unit to the program, then reload. See [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +### "Could not load organisation units" + +- **Kind:** Error +- **Where you see it:** under the context bar. The forms are not shown. The body reads "The organisation units for this program could not be loaded for data entry." +- **What it means:** the app could not read your organisation units or the program's organisation units. +- **What to do:** reload the page. See [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +## Context bar and organisation unit dialog + +### "Required to verify or save" + +- **Kind:** Error +- **Where you see it:** under **Organisation unit** in the context bar. +- **What it means:** you selected **Validate form**, **Verify with server**, **Preview server effects** or **Preview on-complete effects** with no organisation unit. It is a reminder. Only **Verify with server** needs the organisation unit; the others still run. +- **What to do:** select an organisation unit before you use **Verify with server**. See [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md). + +### "Only organisation units assigned to this program can be selected." + +- **Kind:** Info +- **Where you see it:** in the **Select organisation unit** dialog. +- **What it means:** the tree shows your organisation units, but you can only pick the ones assigned to the program. +- **What to do:** pick an organisation unit that isn't greyed out. If the tree is empty apart from this text, see the known issue in [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +### "Not assigned to this program" + +- **Kind:** Info +- **Where you see it:** the tooltip on a greyed-out organisation unit in the tree. +- **What it means:** the organisation unit is shown so you can reach the ones under it, but it isn't assigned to the program. Selecting it does nothing. +- **What to do:** open it and pick an assigned organisation unit below it. + +### "No matching organisation units" + +- **Kind:** Empty +- **Where you see it:** in the **Select organisation unit** dialog, in place of the tree. +- **What it means:** no organisation unit assigned to the program has a name that contains your search term. +- **What to do:** shorten or change the search term. + +## Forms + +### "Could not load enrollment form" + +- **Kind:** Error +- **Where you see it:** in place of the Enrollment form of a tracker program. The body reads "The tracker program metadata could not be loaded." +- **What it means:** the request for the program's attributes and sections failed. +- **What to do:** reload the page. If it keeps happening, [report a bug](../help/report-a-bug.md). + +### "No attributes configured" + +- **Kind:** Empty +- **Where you see it:** in place of the Enrollment form. The body reads "This tracker program does not expose any tracked entity attributes to capture." +- **What it means:** the program has no tracked entity attributes. +- **What to do:** add attributes to the program if you want to test enrollment rules. + +### "This program stage does not have a form to render." + +- **Kind:** Empty +- **Where you see it:** in the form area of a stage. +- **What it means:** the app could not find the stage's metadata. +- **What to do:** check that the stage exists and that you can read it. A stage you have no metadata read access to is left out of the program metadata, so it also causes this message. + +### "No events yet" + +- **Kind:** Empty +- **Where you see it:** under a repeatable stage in the **Enrollment** rail. +- **What it means:** you haven't added an event to this stage. Selecting the stage row does nothing yet. +- **What to do:** select **Add event**. See [Work with repeatable stages](../using-the-app/work-with-repeatable-stages.md). + +### `Hidden by {rule}` and `Section hidden by {rule}` + +- **Kind:** Info +- **Where you see it:** a dashed placeholder where a rule hid a field or a section, while **Show hidden fields** is on. If the app can't name the rule, it says "a rule". +- **What it means:** the named rule hid the field or section. +- **What to do:** nothing. Turn off **Show hidden fields** to leave hidden fields out. See [Read field badges and hidden-field placeholders](../using-the-app/read-field-badges-and-hidden-field-placeholders.md). + +### `On complete: {message}` + +- **Kind:** Info +- **Where you see it:** a dashed note under a field while the form is in completed status. +- **What it means:** an on-complete rule has a message for this field. +- **What to do:** see [Test on-complete rules](../using-the-app/test-on-complete-rules.md). + +### "Warning" and "Error" under a field + +- **Kind:** Warning, Error +- **Where you see it:** under a field. +- **What it means:** a **SHOWWARNING** or **SHOWERROR** rule fired but its action has no text, so the app shows the plain word. When the action has text, the app shows that text instead, without the evaluated data part. +- **What to do:** add text to the rule action if you want a clearer message. + +### "This field is required" + +- **Kind:** Error +- **Where you see it:** under the incident date at the top of the Enrollment form, when the program shows one and it is empty. It also appears in the completion banner, see below. +- **What it means:** the field is required and empty. +- **What to do:** fill it in. + +### File and image fields + +Choosing a file in a file or image field uploads it to the server straight away, as an unassigned file resource. This is the one request besides the dry run that stores something on the server. The upload messages come from the field widget, not from the app. When an upload fails, the field shows the error message from the upload, or "Upload failed" when there is none. + +## Feedback and Indicators sidebar + +### "No feedback rules are firing in this form." and "No indicator rules are firing in this form." + +- **Kind:** Empty +- **Where you see it:** in the **Feedback** and **Indicators** cards. +- **What it means:** no **DISPLAYTEXT** or **DISPLAYKEYVALUEPAIR** rule for that card is firing with the current values. +- **What to do:** change values so the rule's condition is true, or check the rule in the **Rules** tab. See [Read the Feedback and Indicators sidebar](../using-the-app/read-the-feedback-and-indicators-sidebar.md). + +## Validate form + +These notices appear above the form buttons. See [Validate a form](../using-the-app/validate-a-form.md). + +### "Form is valid" + +- **Kind:** Info +- **Where you see it:** with the body "No validation issues were found." +- **What it means:** every field passed its checks. +- **What to do:** nothing. + +### "Form has issues" + +- **Kind:** Error +- **Where you see it:** with a list of field names, each a link to the field. +- **What it means:** one or more fields failed a metadata check: value type, compulsory, options or bounds. Fields that a rule hid are checked too. Rule errors and empty fields that a rule made mandatory are not counted. +- **What to do:** select each field name, fix the value and select **Validate form** again. + +### "Could not validate the form" + +- **Kind:** Error +- **Where you see it:** with the error message as the body. +- **What it means:** the check itself failed. +- **What to do:** try again. If it keeps happening, [report a bug](../help/report-a-bug.md) with the message. + +## Verify with server + +These notices appear above the form buttons. See [Check rules against the server](../using-the-app/check-rules-against-the-server.md). + +### "Server check passed" + +- **Kind:** Info +- **Where you see it:** with the body "Server found no rule errors or warnings." +- **What it means:** the dry run found no rule errors, rule warnings or other import errors. +- **What to do:** nothing. + +### "Server check found issues" + +- **Kind:** Error +- **Where you see it:** with either "The affected fields are highlighted in the form." or a list of "field: message" lines and **Other import errors**. +- **What it means:** the server's rules or validation rejected something. Rule errors on visible fields are shown on those fields. Warnings and results without a visible field are listed in the notice. +- **What to do:** compare with what the playground shows. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md). + +### `Other import errors ({n})` + +- **Kind:** Error +- **Where you see it:** a section inside **Server check found issues**, with one line and a DHIS2 error code per error. +- **What it means:** the server rejected the payload for a reason that is not a program rule, often your access. +- **What to do:** look up the code below. + +The codes you are most likely to see are about access and setup. [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) explains each one and how to fix it: + +| Code | In short | See | +| --- | --- | --- | +| `E1000` | No capture access to the selected organisation unit. | [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) | +| `E1091`, `E1095`, `E1001` | No data write access to the program, the program stage or the tracked entity type. | [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) | +| `E1096`, `E1104` | No data read access. | [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) | +| `E1099` | No write access to the category option. | [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) | +| `E1029`, `E1041` | The selected organisation unit is not assigned to the program. | [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) | + +A stage form in a tracker program sends its event without the tracked entity or enrollment, so the server may report other import errors that are not about your rules. `TODO(verify)`: the codes for that case. + +### "Could not verify with server" + +- **Kind:** Error +- **Where you see it:** with one of these bodies: + - "Select an organisation unit before saving or verifying": you have no organisation unit selected. Select one in the context bar. + - "The form values could not be validated before saving": the app could not build the dry run from the form values. This happens when a field holds a value the dry run can't carry, such as a list of values or a file from a multi-select or file field, or coordinates, or when the event date or enrollment date is missing. + - "An unexpected error occurred": the request failed without a message. + - Any other text is the message from DHIS2, for example after your session expired. +- **What it means:** the dry run did not complete, so there is no new result. +- **What to do:** fix the cause and select **Verify with server** again. See [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md). + +## Completion banner + +The banner appears above the form buttons after **Preview on-complete effects**. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md). + +### "Cannot complete this event yet" + +- **Kind:** Error +- **Where you see it:** with a list of "Error:" and "Required:" lines, and **Back to editing**. +- **What it means:** an **ERRORONCOMPLETE** rule fired, or a required field is empty. A data entry app would not let you complete the event. +- **What to do:** select each field name and fix the value. The banner updates as you go and disappears when nothing is left. + +### "Review before completing" + +- **Kind:** Warning +- **Where you see it:** with a list of "Warning:" lines, **Back to editing** and **Complete anyway**. +- **What it means:** only **WARNINGONCOMPLETE** rules fired. A data entry app would let you complete the event after the warning. +- **What to do:** select **Complete anyway** to see the server effects for a completed event, or **Back to editing**. + +### `Required: {field} – This field is required` + +- **Kind:** Error +- **Where you see it:** a line in the completion banner. +- **What it means:** a visible field that is required, by metadata or by a rule, is empty. +- **What to do:** fill in the field. + +## Server effects dialog + +See [Preview server effects](../using-the-app/preview-server-effects.md) and [Provenance tags](./provenance-tags.md). + +### "Loading server-side actions…" + +- **Kind:** Info +- **Where you see it:** while the dialog opens. +- **What it means:** the app is reading the program's server-side rule actions and notification templates. +- **What to do:** wait. + +### "Could not load server-side actions" + +- **Kind:** Error +- **Where you see it:** in the dialog. +- **What it means:** the request for the rule actions or notification templates failed. +- **What to do:** close the dialog and open it again. If it keeps happening, [report a bug](../help/report-a-bug.md). + +### "No server-side rule effects fired." + +- **Kind:** Empty +- **Where you see it:** in the dialog. +- **What it means:** no notification or event rule fired in the latest evaluation, and the last dry run reported no rule results. +- **What to do:** change values so the rule you want to test fires. + +### "Notification template not found for this action." + +- **Kind:** Warning +- **Where you see it:** in a notification row. +- **What it means:** the rule action has no notification template, or the template could not be found. +- **What to do:** check the template on the rule action. + +### "Invalid date, server will skip" + +- **Kind:** Warning +- **Where you see it:** next to **Scheduled for** in a **SCHEDULEMESSAGE** row. +- **What it means:** the rule's date expression did not give a valid `yyyy-MM-dd` date, so the server would not schedule the message. +- **What to do:** fix the date expression in the rule action. + +### `Not executed by this server` and `Not executed by this server (requires 2.{n})` + +- **Kind:** Warning +- **Where you see it:** on a dashed, dimmed row. +- **What it means:** the server you are connected to does not run this action type. +- **What to do:** treat the row as reference only. See [Provenance tags](./provenance-tags.md). + +### "Use Verify with server on the form to compare against the server." + +- **Kind:** Info +- **Where you see it:** in the dialog footer, before any dry run. +- **What it means:** every row is **Simulated**, because there is no server result yet. +- **What to do:** close the dialog and select **Verify with server**. + +### "The dry run doesn't report notifications, so notification rows stay Simulated." + +- **Kind:** Info +- **Where you see it:** in the dialog footer, after a dry run. +- **What it means:** notification rows can't be confirmed by the server. +- **What to do:** nothing. + +## Rules panel + +### "No program rules match this view." + +- **Kind:** Empty +- **Where you see it:** in the **Rules** tab. +- **What it means:** no rule matches the current view, for example no rule is in scope for this form. +- **What to do:** select **All** to see every rule of the program. In an event program every rule is always shown. + +### "No rules observed yet" + +- **Kind:** Empty +- **Where you see it:** in the **Trace** tab. The body reads "Interact with the form to record rule evaluations. Only rules that have fired at least once appear here." +- **What it means:** the app hasn't recorded any rule evaluation for this form. +- **What to do:** enter a value in the form. See [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md). + +### "No rules fired" + +- **Kind:** Empty +- **Where you see it:** inside an expanded **Trace** entry. +- **What it means:** no rule produced an effect in that evaluation. +- **What to do:** nothing, unless you expected a rule to fire. Then check its condition. + +### "No rule relationships yet" + +- **Kind:** Empty +- **Where you see it:** in the **Graph** tab, with the body "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)." +- **What it means:** the latest evaluation, or the one you selected, has no firing rules. +- **What to do:** enter values so a rule fires. See [Map rule dependencies](../using-the-app/map-rule-dependencies.md). + +### `Applies to enrollment` and `Applies to {stage}` + +- **Kind:** Info +- **Where you see it:** on an **Out of scope** rule card. +- **What it means:** the rule belongs to the Enrollment form or to the named stage, not to the form you have open. In a stage form, rules with no stage show here even when they fire. +- **What to do:** open that form to see the rule in scope. + +## Program rule details dialog + +See [Open and edit a rule](../using-the-app/open-and-edit-a-rule.md). + +### `Could not load this rule: {message}` + +- **Kind:** Error +- **Where you see it:** in the dialog body. +- **What it means:** the request for the rule's details failed. +- **What to do:** close the dialog and try again. + +### "Generating a plain-language description…" + +- **Kind:** Info +- **Where you see it:** under the rule condition. +- **What it means:** the server is writing a plain-language reading of the condition. This request saves nothing. +- **What to do:** wait. The result appears in a box titled "Description". + +### `Could not describe this expression: {message}` + +- **Kind:** Warning +- **Where you see it:** under the rule condition. +- **What it means:** the server returned an error for the condition. The message says why. +- **What to do:** check the condition in the rule editor. + +### "Could not load a plain-language description for this condition. The raw expression is shown above." + +- **Kind:** Warning +- **Where you see it:** under the rule condition. +- **What it means:** the description request failed, for example because of a network problem. +- **What to do:** read the raw condition shown above it. + +### "Read-only view." + +- **Kind:** Info +- **Where you see it:** in the dialog footer, next to the **Edit in Metadata Management app** (DHIS2 2.43) or **Edit in Maintenance app** (2.40 to 2.42) link. +- **What it means:** you can't change the rule here. +- **What to do:** use the link to edit the rule in DHIS2. + +## Related pages + +- [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) +- [Screens and controls](./screens-and-controls.md) +- [Glossary](./glossary.md) diff --git a/docs/reference/provenance-tags.md b/docs/reference/provenance-tags.md index 4d2655e..2ebd8cd 100644 --- a/docs/reference/provenance-tags.md +++ b/docs/reference/provenance-tags.md @@ -1,15 +1,49 @@ --- title: 'Provenance tags' -description: 'Explains the Simulated and Server only tags, and the Not executed by this server message.' +description: 'Explains the Simulated, Server-verified and Server only tags, and the Not executed by this server note, in the Server effects dialog.' sidebar_position: 4 --- # Provenance tags -This page explains the **Simulated** and **Server only** tags, and the **Not executed by this server** message. +This page lists the tags on the rows of the **Server effects** dialog. A provenance tag says where a row comes from: your browser, the server's dry run, or both. -:::info Draft +## Where you see them -This page is a stub. The content is coming in a later release of the docs. +Open the **Server effects** dialog with **Preview server effects** or **Preview on-complete effects**. Each row in **Notifications**, **Events** and **Server validation** has a tag on the right. See [Preview server effects](../using-the-app/preview-server-effects.md). + +## How the app picks a tag + +The app compares the latest rule evaluation in your browser with the last [Verify with server](../using-the-app/check-rules-against-the-server.md) result for the same form. A row matches when the same rule produced the same action type in both. + +- Before you run **Verify with server**, every row from your browser is **Simulated**. +- The dry run doesn't report notifications, so notification rows stay **Simulated** even after a dry run. +- If a later **Verify with server** fails, the app keeps comparing against the last result that completed. + +## Tags + + + + + +| Tag | How it looks | What it means | What to do | +| --- | --- | --- | --- | +| **Simulated** | Blue tag | The effect was evaluated in the browser and has no server report to compare with. | Run **Verify with server** to compare. Notification rows always stay **Simulated**, because the dry run does not report notifications. | +| **Server-verified** | Green tag | The browser and the server both produced this effect. | Nothing. The playground and the server agree. | +| **Server only** | Red tag | The server reported this effect but the browser did not simulate it. | Find out why the playground did not produce it: check the rule condition and the values in the form. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md). | +| **Not executed by this server** | No tag. The row is dashed and dimmed, with the note "Not executed by this server" or "Not executed by this server (requires 2.43)". | The server version does not execute this action type, so it is shown for reference only. | Treat the row as reference only. The server you are connected to will not run this action. | + + + +:::note + +The server runs **SCHEDULEEVENT** on DHIS2 2.43 and later. On DHIS2 2.40 to 2.42, **SCHEDULEEVENT** and **CREATEEVENT** rows show "Not executed by this server (requires 2.43)". On 2.43, **CREATEEVENT** rows show "Not executed by this server", because the server declares the action but doesn't run it. The app reads the server version from the instance and treats an unknown version as 2.40. ::: + +## Related pages + +- [Preview server effects](../using-the-app/preview-server-effects.md) +- [Why client and server results differ](../concepts/why-client-and-server-results-differ.md) +- [Rule action types](./rule-action-types.md) +- [Glossary](./glossary.md) diff --git a/docs/reference/rule-action-types.md b/docs/reference/rule-action-types.md index a93f5e2..29c011e 100644 --- a/docs/reference/rule-action-types.md +++ b/docs/reference/rule-action-types.md @@ -1,15 +1,63 @@ --- title: 'Rule action types' -description: 'Lists the program rule action types, whether each runs on the client or the server, and the DHIS2 versions that support them.' +description: 'Lists the program rule action types, what the playground does with each, whether the server runs it, and the DHIS2 versions involved.' sidebar_position: 2 --- # Rule action types -This page lists the program rule action types, whether each runs on the client or the server, and the DHIS2 versions that support them. +This page lists every program rule action type the app knows, in one table. For each type it shows what the playground does in your browser, whether the DHIS2 server also runs it when data is imported, and any version gate. -:::info Draft +## How to read the table -This page is a stub. The content is coming in a later release of the docs. +- **In the playground** is what you see when a rule with this action fires in a form. +- **Server on 2.40 to 2.42** and **Server on 2.43** say whether the DHIS2 tracker importer runs the action when data is imported, and so whether [Verify with server](../using-the-app/check-rules-against-the-server.md) or the [Server effects](../using-the-app/preview-server-effects.md) dialog can show a server result for it. "Not run" means only data entry apps in the browser run it. This matches [DHIS2 version compatibility](../introduction/dhis2-version-compatibility.md). +- Every action that fires also shows in the **Rules**, **Trace** and **Graph** tabs. + +## Action types + +| Action type | In the playground | Server on 2.40 to 2.42 | Server on 2.43 | +| --- | --- | --- | --- | +| `HIDEFIELD` | Hides the field. Shows a **Hidden** badge and a hidden-field placeholder. | Not run | Not run | +| `SHOWFIELD` | Shows the field again. **Shown** badge. See note 1. | Not run | Not run | +| `HIDESECTION` | Hides the section. Shows a "Section hidden by" placeholder, no badge. | Not run | Not run | +| `HIDEPROGRAMSTAGE` | No effect on the form or the **Enrollment** rail. Visible in the rules panel only. | Not run | Not run | +| `HIDEOPTION` | Removes the option from the field's list. **Hidden** badge. | Not run | Not run | +| `SHOWOPTION` | Puts a hidden option back. **Shown** badge. See note 1. | Not run | Not run | +| `HIDEOPTIONGROUP` | Removes the options in the option group. **Hidden** badge. | Not run | Not run | +| `SHOWOPTIONGROUP` | Puts the options of the option group back. **Shown** badge. See note 1. | Not run | Not run | +| `ASSIGN` | Fills in the value and locks the field. **Assigned** badge. Can also assign to a variable with no field. | Runs | Runs | +| `SETMANDATORYFIELD` | Makes the field required. **Required by rule** badge and an asterisk. | Runs | Runs | +| `UNSETMANDATORYFIELD` | Makes the field optional. **Required by rule** badge. See note 1. | Not run | Not run | +| `SHOWWARNING` | Shows the warning under the field. **Warning** badge. | Runs | Runs | +| `SHOWERROR` | Shows the error under the field. **Error** badge. | Runs | Runs | +| `WARNINGONCOMPLETE` | **On complete: warning** badge. Listed in the completion banner. | Runs | Runs | +| `ERRORONCOMPLETE` | **On complete: error** badge. Blocks completion in the completion banner. | Runs | Runs | +| `DISPLAYTEXT` | Adds an item to the **Feedback** or **Indicators** card. | Not run | Not run | +| `DISPLAYKEYVALUEPAIR` | Adds an item to the **Feedback** or **Indicators** card. | Not run | Not run | +| `SENDMESSAGE` | Not run in the browser. Shown as a **Simulated** row in **Server effects**. | Runs | Runs | +| `SCHEDULEMESSAGE` | Not run in the browser. Shown as a **Simulated** row in **Server effects**, with the scheduled date. | Runs | Runs | +| `SCHEDULEEVENT` | Not run in the browser. Shown in the **Events** section of **Server effects**. | Not run, see note 2 | Runs | +| `CREATEEVENT` | Not run in the browser. Shown in the **Events** section of **Server effects**. | Not run, see note 2 | Not run, see note 2 | + +## Notes + +1. `SHOWFIELD`, `SHOWOPTION`, `SHOWOPTIONGROUP` and `UNSETMANDATORYFIELD` are not in the DHIS2 API type list that the app is built against. The playground handles them if a rule engine result contains them, but you can't configure them as a rule action in the Maintenance or Metadata Management app. +2. On DHIS2 2.40 to 2.42, `SCHEDULEEVENT` and `CREATEEVENT` rows in **Server effects** show "Not executed by this server (requires 2.43)". On 2.43, `CREATEEVENT` rows show "Not executed by this server", because the server declares the action but doesn't run it. See [Provenance tags](./provenance-tags.md). + +:::note + +The app reads the DHIS2 version from the instance. If it can't tell the version, it treats the server as 2.40. ::: + +- An `ERRORONCOMPLETE` or `WARNINGONCOMPLETE` action with no field still counts in the completion banner, as a message without a field name. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md). +- Warning and error texts under a field show the action's static text only. The evaluated data part is not added, unlike in the DHIS2 Capture app. +- `HIDEOPTIONGROUP` and `SHOWOPTIONGROUP` need read access to the option group. `TODO(verify)`: what you see when you don't have it. + +## Related pages + +- [Effect badges legend](./effect-badges-legend.md) +- [Provenance tags](./provenance-tags.md) +- [How program rules are evaluated](../concepts/how-program-rules-are-evaluated.md) +- [Why client and server results differ](../concepts/why-client-and-server-results-differ.md) diff --git a/docs/reference/screens-and-controls.md b/docs/reference/screens-and-controls.md index 40bc389..a35adf1 100644 --- a/docs/reference/screens-and-controls.md +++ b/docs/reference/screens-and-controls.md @@ -1,15 +1,105 @@ --- title: 'Screens and controls' -description: 'Describes every screen and control in the app, with annotated screenshots.' +description: 'Describes each screen of the app and the controls on it, with screenshots and links to the task pages.' sidebar_position: 1 --- # Screens and controls -This page describes every screen and control in the app, with annotated screenshots. +This page goes through the app screen by screen. For each screenshot, the numbered list names the controls you can see, from top left to bottom right, and links to the page that explains how to use them. -:::info Draft +The app has three screens: the program list, the playground for one program, and the About page. -This page is a stub. The content is coming in a later release of the docs. +## Program list -::: +The first screen when you open the app. It lists the programs you can see. + +![Program list filtered by the search term PRT, showing one event program and one tracker program](../using-the-app/img/program-list.png) + +1. **Programs** heading, with "Pick a program to open its forms and watch its rules evaluate." under it. +2. Search field, "Search by name, code, or ID". It filters the list as you type. See [Find and open a program](../using-the-app/find-and-open-a-program.md). +3. Type switch, **All**, **Tracker** or **Event**. +4. Program table, with the columns **Program** (name and ID), **Type**, **Stages** and **Last updated**. Select a row to open the program in the playground. +5. Page controls under the table, to move between pages and change how many programs show per page. The default is 10. +6. **Docs** and **About** links at the bottom right. **Docs** opens this site in a new tab. **About** opens the About page. + +## Playground + +The screen for one program. It has the context bar at the top, then the form area. In a tracker program, the **Enrollment** rail sits on the left of the form. + +### Context bar + +![Context bar with the back link, program name, organisation unit, event date and Reset playground](../using-the-app/img/context-bar.png) + +1. **Programs** back link. It returns to the program list, with your search, type and page as you left them. See [Find and open a program](../using-the-app/find-and-open-a-program.md). +2. Program name, with the program type (**Tracker** or **Event program**) and the number of rules under it. +3. **Organisation unit**, with **Select** (or **Change** once one is set). It opens the **Select organisation unit** dialog. Only **Verify with server** needs an organisation unit. See [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md). +4. **Event date** in an event program, or **Enrollment date** in a tracker program. It defaults to today. See [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md). +5. **Reset playground**. It clears the organisation unit, sets the date back to today and empties every form. See [Start over](../using-the-app/start-over.md). + +### Form + +![Event form with Hidden, Warning, Assigned and Required by rule badges and a hidden-field placeholder](../using-the-app/img/event-form-badges.png) + +1. **Show hidden fields**, at the top right of the fields. When it is on (teal), a placeholder marks each field or section a rule hid. When it is off (grey), they are left out. See [Read field badges and hidden-field placeholders](../using-the-app/read-field-badges-and-hidden-field-placeholders.md). +2. Section cards, each with the section name and the number of fields in it. +3. Effect badges next to field labels, such as **Hidden**, **Warning**, **Assigned** and **Required by rule**. See the [Effect badges legend](./effect-badges-legend.md). +4. Hidden-field placeholder, "Hidden by" followed by the rule name, or "Section hidden by" for a whole section. +5. **Feedback** and **Indicators** cards, to the right of the fields. See [Read the Feedback and Indicators sidebar](../using-the-app/read-the-feedback-and-indicators-sidebar.md). +6. Form buttons, under the fields: + - **Validate form**. See [Validate a form](../using-the-app/validate-a-form.md). + - **Verify with server**. See [Check rules against the server](../using-the-app/check-rules-against-the-server.md). + - **Preview server effects**. See [Preview server effects](../using-the-app/preview-server-effects.md). + - **Preview on-complete effects**, on event forms only. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md). +7. Rules panel, docked on the right. See the next section. + +The Enrollment form of a tracker program has **Validate form**, **Verify with server** and **Preview server effects** only. + +### Rules panel + +![Rules panel on the Rules tab, with firing rules sorted to the top](../using-the-app/img/rules-tab.png) + +1. **Rules** title, with the counter "n in scope · n firing". +2. **In scope** / **All** switch. It only shows in tracker programs. In an event program every rule is in scope. +3. Tabs: **Rules**, **Trace** and **Graph**. +4. Rule cards, firing rules first. Each card shows: + - the rule name and its status, **Firing**, **Idle** or **Out of scope** + - an info button, **Program rule details**, that opens the rule's details. See [Open and edit a rule](../using-the-app/open-and-edit-a-rule.md). + - one effect badge per action, such as "ASSIGN · Assigned value (number x 2)" + - the rule condition + - for an out-of-scope rule, where it applies: "Applies to enrollment" or "Applies to" followed by a stage name + +Selecting a card highlights the rule and switches to the **Graph** tab. See [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md) for the **Rules** and **Trace** tabs, and [Map rule dependencies](../using-the-app/map-rule-dependencies.md) for the **Graph** tab. + +### Enrollment rail + +In a tracker program, the **Enrollment** rail on the left lists the forms of one enrollment. + +![Tracker program with the enrollment rail, a repeatable stage holding two events, and the second event open](../using-the-app/img/tracker-repeatable-stage.png) + +1. **Enrollment** heading. +2. **Enrollment form**, with the number of attributes. It is selected when you open the program. +3. One row per program stage. A stage that is not repeatable shows "1 event". +4. A repeatable stage shows "No events yet", "1 event" or "n events", and an **Add event** button. +5. The events you added, as "Event 1", "Event 2" and so on, under their stage. + +Switching rows keeps what you entered in every form. See [Work with repeatable stages](../using-the-app/work-with-repeatable-stages.md). + +## Dialogs + +| Dialog | Opened from | See | +| --- | --- | --- | +| **Select organisation unit** | **Select** or **Change** in the context bar | [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md) | +| Program rule details | **Program rule details** on a rule card, or a rule name in **Server effects** | [Open and edit a rule](../using-the-app/open-and-edit-a-rule.md) | +| **Server effects** | **Preview server effects** or **Preview on-complete effects** | [Preview server effects](../using-the-app/preview-server-effects.md) | +| **Rule dependency graph** | The full-screen button on the **Graph** tab | [Map rule dependencies](../using-the-app/map-rule-dependencies.md) | + +## About page + +Open it from **About** at the bottom of the program list. It shows the app **Version**, the **Supported DHIS2** versions and a **Resources** list: **Documentation**, **GitHub repository**, **Report a bug** and **dhis2-form-utils**. Each resource opens in a new tab. **← Back to programs** returns to the program list, without your earlier search. + +## Related pages + +- [Glossary](./glossary.md) +- [Messages and errors](./messages-and-errors.md) +- [Effect badges legend](./effect-badges-legend.md) diff --git a/package.json b/package.json index ee7fd7a..030016e 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "clear": "docusaurus clear", "typecheck": "tsc --noEmit && tsc --noEmit -p scripts", "format": "prettier --write .", + "generate:reference": "node --experimental-strip-types scripts/generate-reference.mts", "lint": "prettier --check . && pnpm typecheck && markdownlint-cli2", "prepare": "husky", "screenshots": "node --env-file-if-exists=.env scripts/screenshots/run.mts", diff --git a/scripts/data/legend.json b/scripts/data/legend.json new file mode 100644 index 0000000..0eba7ed --- /dev/null +++ b/scripts/data/legend.json @@ -0,0 +1,176 @@ +{ + "_sources": { + "EFFECT_LEGEND": "node_modules/@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14 src/constants/legend.ts:34-63", + "PROVENANCE_TAGS": "node_modules/@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14 src/constants/legend.ts:74-101", + "visuals": "node_modules/@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14 src/styles/effectStyles.ts:35-124", + "tagProps": "node_modules/@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14 src/styles/effectStyles.ts:152-173", + "ProvenanceTag render": "node_modules/@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14 src/components/ServerEffectsSummary/ProvenanceTag.tsx:9-31", + "field badge labels": "src/modules/program-playground/components/rules/FieldEffectBadge.tsx:10-17" + }, + "_notes": [ + "EFFECT_LEGEND is rendered only in the Graph toolbar (EffectLegend), filtered to variants present on current graph edges, label only (description is never shown in UI).", + "Variant message (SENDMESSAGE/SCHEDULEMESSAGE/SCHEDULEEVENT/CREATEEVENT) and default have visuals but NO EFFECT_LEGEND entry.", + "PROVENANCE_TAGS descriptions are not rendered in UI. not-executed is never rendered as a Tag; the row prints \"Not executed by this server\" or \"Not executed by this server (requires 2.{{minor}})\" and is dashed/dimmed.", + "Colour classes are Tailwind tokens mapped to DHIS2 palette; edgeStroke is the hex used for graph edges and the action card left border in the details modal." + ], + "EFFECT_LEGEND": [ + { + "variant": "read", + "label": "Read", + "description": "The rule reads this field in its condition.", + "icon": "IconLink16", + "tagClassName": "bg-dhis2-teal-100 text-dhis2-teal-900", + "edgeStroke": "#00796b", + "shortLabel": "read", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["read (graph edge only)"], + "fieldBadgeLabel": "read (shortLabel fallback, lowercase)" + }, + { + "variant": "hide", + "label": "Hide", + "description": "The rule hides a field, section, option or stage.", + "icon": "IconViewOff16", + "tagClassName": "bg-dhis2-grey-200 text-dhis2-grey-900", + "edgeStroke": "#494949", + "shortLabel": "hide", + "dhis2TagVariant": "none (className colours)", + "actionTypes": [ + "HIDEFIELD", + "HIDEOPTION", + "HIDEOPTIONGROUP", + "HIDESECTION", + "HIDEPROGRAMSTAGE" + ], + "fieldBadgeLabel": "Hidden" + }, + { + "variant": "show", + "label": "Show", + "description": "The rule shows a field or option.", + "icon": "IconView16", + "tagClassName": "bg-dhis2-green-100 text-dhis2-green-900", + "edgeStroke": "#388e3c", + "shortLabel": "show", + "dhis2TagVariant": "positive", + "actionTypes": ["SHOWFIELD", "SHOWOPTION", "SHOWOPTIONGROUP"], + "fieldBadgeLabel": "Shown" + }, + { + "variant": "assign", + "label": "Assign", + "description": "The rule assigns a value to a field.", + "icon": "IconEdit16", + "tagClassName": "bg-dhis2-blue-100 text-dhis2-blue-900", + "edgeStroke": "#1565c0", + "shortLabel": "assign", + "dhis2TagVariant": "neutral", + "actionTypes": ["ASSIGN"], + "fieldBadgeLabel": "Assigned" + }, + { + "variant": "mandatory", + "label": "Required", + "description": "The rule makes a field required or optional.", + "icon": "IconStarFilled16", + "tagClassName": "bg-dhis2-yellow-100 text-dhis2-yellow-900", + "edgeStroke": "#e56408", + "shortLabel": "required", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["SETMANDATORYFIELD", "UNSETMANDATORYFIELD"], + "fieldBadgeLabel": "Required by rule" + }, + { + "variant": "warning", + "label": "Warning", + "description": "The rule shows a warning message.", + "icon": "IconWarningFilled16", + "tagClassName": "bg-dhis2-yellow-100 text-dhis2-yellow-900", + "edgeStroke": "#ff8302", + "shortLabel": "warn", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["SHOWWARNING", "WARNINGONCOMPLETE"], + "fieldBadgeLabel": "Warning" + }, + { + "variant": "error", + "label": "Error", + "description": "The rule shows an error and blocks saving.", + "icon": "IconErrorFilled16", + "tagClassName": "bg-dhis2-red-100 text-dhis2-red-900", + "edgeStroke": "#c62828", + "shortLabel": "error", + "dhis2TagVariant": "negative", + "actionTypes": ["SHOWERROR", "ERRORONCOMPLETE"], + "fieldBadgeLabel": "Error" + }, + { + "variant": "feedback", + "label": "Feedback", + "description": "The rule displays text or a key-value pair in the feedback widget.", + "icon": "IconMessages16", + "tagClassName": "bg-dhis2-purple-100 text-dhis2-purple-900", + "edgeStroke": "#9c27b0", + "shortLabel": "feedback", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["DISPLAYTEXT", "DISPLAYKEYVALUEPAIR"], + "fieldBadgeLabel": "feedback (shortLabel fallback, lowercase)" + } + ], + "OTHER_VARIANTS_NOT_IN_LEGEND": [ + { + "variant": "message", + "icon": "IconMail16", + "tagClassName": "bg-dhis2-teal-100 text-dhis2-teal-900", + "edgeStroke": "#00796b", + "shortLabel": "message", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["SENDMESSAGE", "SCHEDULEMESSAGE", "SCHEDULEEVENT", "CREATEEVENT"], + "fieldBadgeLabel": "message (shortLabel fallback, lowercase)" + }, + { + "variant": "default", + "icon": "IconInfo16", + "tagClassName": "bg-dhis2-grey-100 text-dhis2-grey-800", + "edgeStroke": "#494949", + "shortLabel": "effect", + "dhis2TagVariant": "none (className colours)", + "actionTypes": ["any other"], + "fieldBadgeLabel": "effect (shortLabel fallback, lowercase)" + } + ], + "PROVENANCE_TAGS": [ + { + "id": "simulated", + "label": "Simulated", + "description": "The effect was evaluated in the browser and has no server report to compare with.", + "dhis2Tag": "neutral", + "dataTest": "devtools-provenance-simulated", + "when": "Notification/event row from the browser trace whose (ruleId, actionType) is not in the last Verify with server report (notifications are never in the report, so they always stay Simulated)" + }, + { + "id": "server-verified", + "label": "Server-verified", + "description": "The browser and the server both produced this effect.", + "dhis2Tag": "positive", + "dataTest": "devtools-provenance-server-verified", + "when": "Browser trace effect also present in the dry-run report (same ruleId + actionType)" + }, + { + "id": "server-only", + "label": "Server only", + "description": "The server reported this effect but the browser did not simulate it.", + "dhis2Tag": "negative", + "dataTest": "devtools-provenance-server-only", + "when": "Dry-run report entry with no matching browser effect" + }, + { + "id": "not-executed", + "label": "Not executed by this server", + "description": "The server version does not execute this action type, so it is shown for reference only.", + "dhis2Tag": "not rendered as Tag", + "dataTest": "devtools-provenance-not-executed (on the note

)", + "when": "Action type not executed by server minor (SCHEDULEEVENT/CREATEEVENT < 2.43) or declared-but-not-executed (CREATEEVENT always)" + } + ] +} diff --git a/scripts/generate-reference.mts b/scripts/generate-reference.mts new file mode 100644 index 0000000..1fef5af --- /dev/null +++ b/scripts/generate-reference.mts @@ -0,0 +1,241 @@ +/** + * Writes the generated tables of the effect badges legend and the provenance tags + * reference pages, between their `` and `` + * markers. + * + * Source: `scripts/data/legend.json`, a dump of `EFFECT_LEGEND` and `PROVENANCE_TAGS` + * from `@nnkogift/dhis2-form-utils-devtools@0.1.0-alpha.14` (src/constants/legend.ts, + * src/styles/effectStyles.ts, recovered from the package source maps), plus the field + * badge labels the app owns (src/modules/program-playground/components/rules/FieldEffectBadge.tsx). + * The package itself can't be imported in Node: it pulls in `@dhis2/ui`, which needs browser + * globals and `styled-jsx`. Refresh the JSON when the devtools package is upgraded. + * + * Run: pnpm generate:reference + */ +import { readFileSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +type Variant = { + variant: string; + label?: string; + description?: string; + icon: string; + tagClassName: string; + edgeStroke: string; + actionTypes: string[]; + fieldBadgeLabel: string; +}; + +type ProvenanceTag = { + id: string; + label: string; + description: string; + dhis2Tag: string; +}; + +type Legend = { + EFFECT_LEGEND: Variant[]; + OTHER_VARIANTS_NOT_IN_LEGEND: Variant[]; + PROVENANCE_TAGS: ProvenanceTag[]; +}; + +const root = join(dirname(fileURLToPath(import.meta.url)), '..'); +const legend = JSON.parse(readFileSync(join(root, 'scripts/data/legend.json'), 'utf8')) as Legend; + +const ICON_NAMES: Record = { + IconLink16: 'Link', + IconViewOff16: 'Eye, crossed out', + IconView16: 'Eye', + IconEdit16: 'Pencil', + IconStarFilled16: 'Star', + IconWarningFilled16: 'Warning', + IconErrorFilled16: 'Error', + IconMessages16: 'Speech bubbles', + IconMail16: 'Envelope', + IconInfo16: 'Info', +}; + +/** Where each variant shows up when it has no badge on a field. */ +const NO_FIELD_BADGE: Record = { + read: 'None. Graph edges only.', + feedback: 'None. Shown in the **Feedback** or **Indicators** card.', + message: 'None. Shown in the **Server effects** dialog.', + default: 'None.', +}; + +/** What a reader should do about each provenance tag. Every tag must have an entry. */ +const PROVENANCE_ADVICE: Record = { + simulated: { + appearance: 'Blue tag', + whatToDo: + 'Run **Verify with server** to compare. Notification rows always stay **Simulated**, because the dry run does not report notifications.', + }, + 'server-verified': { + appearance: 'Green tag', + whatToDo: 'Nothing. The playground and the server agree.', + }, + 'server-only': { + appearance: 'Red tag', + whatToDo: + 'Find out why the playground did not produce it: check the rule condition and the values in the form. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md).', + }, + 'not-executed': { + appearance: + 'No tag. The row is dashed and dimmed, with the note "Not executed by this server" or "Not executed by this server (requires 2.43)".', + whatToDo: + 'Treat the row as reference only. The server you are connected to will not run this action.', + }, +}; + +const TAG_APPEARANCE_CHECK: Record = { + neutral: 'simulated', + positive: 'server-verified', + negative: 'server-only', +}; + +function cell(text: string): string { + return text.replace(/\|/g, '\\|').replace(/\n/g, ' '); +} + +function colourName(tagClassName: string): string { + const match = /bg-dhis2-([a-z]+)-\d+/.exec(tagClassName); + if (!match) { + throw new Error(`Unknown tag colour: ${tagClassName}`); + } + return match[1][0].toUpperCase() + match[1].slice(1); +} + +function swatch(hex: string): string { + return ` \`${hex}\``; +} + +/** Action types that show no field badge, although their variant has one. */ +const NO_BADGE_TYPES = new Set(['HIDESECTION', 'HIDEPROGRAMSTAGE']); + +/** + * Action types whose field badge is "On complete: " plus the lowercased variant badge + * label (FieldEffectBadge.tsx, `onComplete`). + */ +const ON_COMPLETE_TYPES = new Set(['WARNINGONCOMPLETE', 'ERRORONCOMPLETE']); + +function fieldBadge(variant: Variant): string { + if (variant.variant in NO_FIELD_BADGE) { + return NO_FIELD_BADGE[variant.variant]; + } + const parts = [`**${variant.fieldBadgeLabel}**`]; + const noBadge = variant.actionTypes.filter((type) => NO_BADGE_TYPES.has(type)); + if (noBadge.length) { + parts.push(`${noBadge.map((type) => `\`${type}\``).join(' and ')}: none.`); + } + for (const type of variant.actionTypes.filter((t) => ON_COMPLETE_TYPES.has(t))) { + parts.push(`\`${type}\`: **On complete: ${variant.fieldBadgeLabel.toLowerCase()}**.`); + } + if (parts.length > 1) { + const typed = new Set([...NO_BADGE_TYPES, ...ON_COMPLETE_TYPES]); + const plain = variant.actionTypes.filter((type) => !typed.has(type)); + parts[0] = `${plain.map((type) => `\`${type}\``).join(', ')}: ${parts[0]}.`; + } + return parts.join(' '); +} + +function icon(name: string): string { + const label = ICON_NAMES[name]; + if (!label) { + throw new Error(`Add a name for icon ${name} to ICON_NAMES.`); + } + return label; +} + +/** Action types as code; the legend's free-text entries become plain sentences. */ +function actionTypes(variant: Variant): string { + if (variant.variant === 'read') { + return 'None. The condition reads the field.'; + } + return variant.actionTypes + .map((type) => (/^[A-Z]+$/.test(type) ? `\`${type}\`` : 'Any other action type')) + .join(', '); +} + +function variantRow(variant: Variant, inLegend: boolean): string { + const cells = [ + inLegend ? `**${variant.label}**` : `\`${variant.variant}\``, + fieldBadge(variant), + actionTypes(variant), + icon(variant.icon), + colourName(variant.tagClassName), + swatch(variant.edgeStroke), + ]; + if (inLegend) { + cells.push(cell(variant.description ?? '')); + } + return `| ${cells.join(' | ')} |`; +} + +function effectTables(): string { + const header = [ + '| Graph legend | Field badge | Action types | Icon | Badge colour | Graph edge | Meaning |', + '| --- | --- | --- | --- | --- | --- | --- |', + ]; + const others = [ + '| Variant | Field badge | Action types | Icon | Badge colour | Graph edge |', + '| --- | --- | --- | --- | --- | --- |', + ]; + return [ + '### In the graph legend', + '', + ...header, + ...legend.EFFECT_LEGEND.map((variant) => variantRow(variant, true)), + '', + '### Not in the graph legend', + '', + 'These variants have an icon and colours, but no entry in the legend.', + '', + ...others, + ...legend.OTHER_VARIANTS_NOT_IN_LEGEND.map((variant) => variantRow(variant, false)), + ].join('\n'); +} + +function provenanceTable(): string { + const rows = legend.PROVENANCE_TAGS.map((tag) => { + const advice = PROVENANCE_ADVICE[tag.id]; + if (!advice) { + throw new Error(`Add advice for provenance tag "${tag.id}" to PROVENANCE_ADVICE.`); + } + const expectedId = TAG_APPEARANCE_CHECK[tag.dhis2Tag]; + if (expectedId && expectedId !== tag.id) { + throw new Error(`Provenance tag "${tag.id}" changed colour (${tag.dhis2Tag}).`); + } + return `| **${tag.label}** | ${cell(advice.appearance)} | ${cell(tag.description)} | ${cell(advice.whatToDo)} |`; + }); + return [ + '| Tag | How it looks | What it means | What to do |', + '| --- | --- | --- | --- |', + ...rows, + ].join('\n'); +} + +const START = ''; +const END = ''; +const NOTICE = + ''; + +function writeBetweenMarkers(relativePath: string, content: string): void { + const path = join(root, relativePath); + const page = readFileSync(path, 'utf8'); + const start = page.indexOf(START); + const end = page.indexOf(END); + if (start === -1 || end === -1 || end < start) { + throw new Error(`${relativePath} needs ${START} and ${END} markers.`); + } + const next = `${page.slice(0, start + START.length)}\n\n${NOTICE}\n\n${content}\n\n${page.slice(end)}`; + if (next !== page) { + writeFileSync(path, next); + console.log(`Updated ${relativePath}`); + } else { + console.log(`${relativePath} is up to date`); + } +} + +writeBetweenMarkers('docs/reference/effect-badges-legend.md', effectTables()); +writeBetweenMarkers('docs/reference/provenance-tags.md', provenanceTable());