diff --git a/docs/concepts/how-program-rules-are-evaluated.md b/docs/concepts/how-program-rules-are-evaluated.md index 61d12f7..1c7f8f9 100644 --- a/docs/concepts/how-program-rules-are-evaluated.md +++ b/docs/concepts/how-program-rules-are-evaluated.md @@ -1,15 +1,81 @@ --- title: 'How program rules are evaluated' -description: 'Explains how the client rule engine and the server importer each evaluate program rules.' +description: 'Explains how the rule engine in your browser and the DHIS2 tracker importer each evaluate program rules, and when each one runs.' sidebar_position: 1 --- # How program rules are evaluated -This page explains how the client rule engine and the server importer each evaluate program rules. +## The short version -:::info Draft +Program rules run in two places. The rule engine in your browser evaluates them every time a value in the form changes, and shows the result on the fields, in the sidebar and in the rules panel. The DHIS2 server evaluates them again in its tracker importer, which the app only reaches through **Verify with server**, a dry run that saves nothing. -This page is a stub. The content is coming in a later release of the docs. +## How it works -::: +### In the browser + +The app runs the DHIS2 rule engine (`@dhis2/rule-engine`) in your browser, through the `dhis2-form-utils` libraries. Each form has its own engine. + +The engine evaluates the rules: + +- Once when the form opens. The **Trace** tab shows this evaluation with the **Initial** tag, which marks any evaluation with no changed field. +- After every value change in the form. Changes are grouped: the engine waits about 40 ms after the last change, then evaluates once with all the fields that changed. +- After an **ASSIGN** action changes a value. The app writes the assigned value into the field, and that change causes another evaluation. Its **Trace** entry lists the assigned field under **Changed fields**. +- When the organisation unit or the date in the context bar changes, because both are passed to the form as values. +- In a tracker program, when a value changes in another form of the same enrollment. Each form shares its values with the other forms about 150 ms after you stop typing, and the forms that receive them evaluate their rules again. The **Trace** tab records this re-evaluation with the **Initial** tag, because no field changed in the form itself. If an **ASSIGN** action then changes a value, a second entry that names the assigned field follows. + +Which rules each form evaluates: + +- An event program form, or a stage form in a tracker program, evaluates the rules that have no program stage, plus the rules of its own stage. +- The **Enrollment form** evaluates only the rules that have no program stage. + +The engine returns a list of effects. The app applies them right away: + +- Field effects (hide, show, assign, mandatory, warning, error, options) change the field and add an effect badge. +- **HIDESECTION** effects replace the section body with a hidden-field placeholder. +- **DISPLAYTEXT** and **DISPLAYKEYVALUEPAIR** effects go to the **Feedback** and **Indicators** sidebar. +- Every evaluation is added to the **Trace** tab, and the latest one drives the **Rules** tab statuses and the **Graph** tab. +- Actions that only the server performs (**SENDMESSAGE**, **SCHEDULEMESSAGE**, **SCHEDULEEVENT**, **CREATEEVENT**) are not executed. They appear in the trace and in the **Server effects** dialog as simulated rows. + +```mermaid +flowchart LR + A[You change a value] --> B[Rule engine in the browser evaluates the rules] + B --> C[Fields: badges, hidden-field placeholders, warnings and errors] + B --> D[Sidebar: Feedback and Indicators] + B --> E[Rules panel: Rules, Trace and Graph] +``` + +**Preview on-complete effects** runs one extra pass, the completion pass. The app sets the form status to `COMPLETED`, waits for the engine to evaluate again, and lists the on-complete warnings, errors and empty required fields it finds. See [Test on-complete rules](../using-the-app/test-on-complete-rules.md). + +### On the server + +The DHIS2 server evaluates program rules in its tracker importer when data is imported. The app never imports data. **Verify with server** sends the form to `POST /api/tracker?importMode=VALIDATE&async=false`. With `importMode=VALIDATE` the importer runs its validation and its program rules, reports what it found, and saves nothing. + +The app then reads the report: + +- Errors and warnings that a program rule produced are matched to the rule. Errors on a field that is on screen are shown on that field. +- Anything else is listed in the notice above the form buttons, and other import errors are listed under **Other import errors**. +- The server results also feed the **Server effects** dialog, where rows the browser and the server both produced are tagged **Server-verified** and rows only the server reported are tagged **Server only**. + +```mermaid +flowchart LR + A[You select Verify with server] --> B[Dry run: POST /api/tracker with importMode=VALIDATE] + B --> C[Server runs its program rules and validation] + C --> D[Results: errors on fields, notice above the buttons, Server effects dialog] +``` + +Only **Verify with server** contacts the importer, and it is the only action that needs an organisation unit. **Validate form**, **Preview server effects** and **Preview on-complete effects** work in the browser only. + +## Why it matters + +- What you see while you type is the browser engine's result. It is fast and covers every rule, but it is not the server's answer. +- **Verify with server** is how you check that the server agrees. The two can disagree, for reasons explained in [Why client and server results differ](./why-client-and-server-results-differ.md). +- Because the engine runs on every change, the **Trace** tab can show you the exact change that made a rule fire or stop firing. + +## Related pages + +- [Rule inputs](./rule-inputs.md) +- [Why client and server results differ](./why-client-and-server-results-differ.md) +- [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md) +- [Check rules against the server](../using-the-app/check-rules-against-the-server.md) +- [Is it safe on production?](../introduction/is-it-safe-on-production.md) diff --git a/docs/concepts/rule-inputs.md b/docs/concepts/rule-inputs.md index 6c0ea85..11128e3 100644 --- a/docs/concepts/rule-inputs.md +++ b/docs/concepts/rule-inputs.md @@ -1,15 +1,84 @@ --- title: 'Rule inputs' -description: 'Explains the inputs a rule can read: enrollment, events, user groups and roles, and option groups.' +description: 'Explains what the app gives the rule engine to evaluate: form values, values from other forms of the enrollment, user groups and roles, option groups, constants, the organisation unit, dates and the event status.' sidebar_position: 2 --- # Rule inputs -This page explains the inputs a rule can read: enrollment, events, user groups and roles, and option groups. +## The short version -:::info Draft +A program rule can only react to what the rule engine is given. The app gives it the values in the form you have open, and in a tracker program also the values from the enrollment and from the other stage forms. It adds your user groups and roles, the program's constants, the selected organisation unit, the dates from the context bar and the event status. If a rule depends on something that is not in this list, it evaluates as if that value were empty. -This page is a stub. The content is coming in a later release of the docs. +## How it works -::: +### Values in the form + +Every field in the form you have open is an input, whether you typed the value or a rule assigned it. The engine evaluates again after each change, see [How program rules are evaluated](./how-program-rules-are-evaluated.md). + +### Values from other forms (tracker programs) + +In a tracker program all forms of the enrollment stay open in the background, so the values you entered in one form are available to the rules in the others: + +- A stage form receives the values of the **Enrollment form** as the enrollment, so rules that read tracked entity attributes (`A{...}`) work in stage forms. +- A stage form also receives the values of every other stage form and event in the rail as the enrollment's other events. Its own values are not repeated in that list. This is what feeds program rule variables with the source types `DATAELEMENT_PREVIOUS_EVENT`, `DATAELEMENT_NEWEST_EVENT_PROGRAM` and `DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE`. +- The **Enrollment form** receives the values of all stage forms and events as the enrollment's events. + +Values from other forms arrive about 150 ms after you stop typing. Every non-repeatable stage in the rail, and every event you add to a repeatable stage with **Add event**, counts as an event as soon as it exists, even if you have not entered anything in it yet. + +```mermaid +flowchart LR + E[Enrollment form] -- attributes as the enrollment --> S1[Stage form] + S2[Other stage forms and events] -- values as other events --> S1 + S1 -- values as events --> E +``` + +### User groups and roles + +When a program opens, the app reads your user groups and user roles from `/api/me` and passes their IDs to the engine. Rules that use `d2:inUserGroup` or `d2:hasUserRole` evaluate against your own account, not against the users who enter data in production. Test with an account that has the groups or roles you want to check. + +The app does not pass organisation unit group memberships, so `d2:inOrgUnitGroup` has nothing to match against and always returns false in the app. + +### Option groups + +If a rule action uses **HIDEOPTIONGROUP** or **SHOWOPTIONGROUP**, the app fetches those option groups from `/api/optionGroups` to know which options they contain. If you cannot read an option group, those actions are expected to hide or show nothing, without a message. `TODO(verify)`: this case has not been tested. + +### Constants + +The app loads every constant in the instance (`/api/constants`, ID and value) and passes them to the engine, so `C{...}` in a condition or expression resolves. + +### Organisation unit + +The organisation unit you select in the context bar is the event's organisation unit, and in a tracker program the enrollment's. Until you select one, the engine evaluates without an organisation unit. Its code is not passed, so `V{orgunit_code}` is empty. + +### Dates + +| Form | Date the engine uses | +| --- | --- | +| Event program form | The **Event date** from the context bar, as the event date. | +| **Enrollment form** | The **Enrollment date** from the context bar, as the enrollment date. The incident date is the **Incident date** field when the program shows one, otherwise the enrollment date. | +| Tracker stage form or event | Today. Each event gets today's date when it is first shown and keeps it, and stage forms have no date field. | + +Because all events in a tracker program share today's date, rules that compare events by date, such as rules on the previous event, depend on an order the app does not control. + +### Event status + +The event you have open has the status `ACTIVE`. **Preview on-complete effects** sets it to `COMPLETED` for the completion pass, so the engine evaluates the on-complete rules, and **Back to editing** or closing the **Server effects** dialog sets it back to `ACTIVE`. The other events of an enrollment are always `ACTIVE`, and the enrollment itself is always active. + +### What the server receives + +**Verify with server** sends a different set of inputs: the payload a save would send, without the values of fields a rule hid. See [Why client and server results differ](./why-client-and-server-results-differ.md). + +## Why it matters + +- When a rule does not fire, check its inputs first. The **Trace** tab shows which fields changed in each evaluation, and the rule details show the variables the condition reads. +- To test a rule that reads values from another stage, enter those values in the other stage form first, then come back. +- To test rules on user groups or roles, log in as a user who has them. + +## Related pages + +- [How program rules are evaluated](./how-program-rules-are-evaluated.md) +- [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md) +- [Work with repeatable stages](../using-the-app/work-with-repeatable-stages.md) +- [Test on-complete rules](../using-the-app/test-on-complete-rules.md) +- [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md) diff --git a/docs/concepts/why-client-and-server-results-differ.md b/docs/concepts/why-client-and-server-results-differ.md index 50abc0d..317e66c 100644 --- a/docs/concepts/why-client-and-server-results-differ.md +++ b/docs/concepts/why-client-and-server-results-differ.md @@ -1,15 +1,82 @@ --- title: 'Why client and server results differ' -description: 'Explains why the app and the DHIS2 server can report different results for the same input.' +description: 'Explains why the rule engine in your browser and the DHIS2 server can report different results for the same form.' sidebar_position: 3 --- # Why client and server results differ -This page explains why the app and the DHIS2 server can report different results for the same input. +## The short version -:::info Draft +The browser and the server run program rules separately, and they do not always see the same thing. Some actions only the server can perform, some only run on newer DHIS2 versions, the dry run does not report notifications, and **Verify with server** sends the server a narrower set of inputs than the browser engine uses. When the results differ, it is usually one of these reasons, not a broken rule. -This page is a stub. The content is coming in a later release of the docs. +## How it works + +### Actions only the server runs + +The browser engine does not execute **SENDMESSAGE**, **SCHEDULEMESSAGE**, **SCHEDULEEVENT** or **CREATEEVENT**. When one of these rules fires, the app records the effect in the trace and shows it in the **Server effects** dialog, but nothing is sent or created. Open the dialog with **Preview server effects** or **Preview on-complete effects** to see what the server would do. + +The other way round, the server can report a rule effect the browser did not produce. The **Server effects** dialog tags such a row **Server only**. + +### Version gates + +The server only executes an action type if your DHIS2 version supports it. The app reads the version of the instance and compares: + +| Action type | Executed by the server | +| --- | --- | +| **SENDMESSAGE**, **SCHEDULEMESSAGE**, **ASSIGN**, **SETMANDATORYFIELD**, **SHOWERROR**, **SHOWWARNING**, **ERRORONCOMPLETE**, **WARNINGONCOMPLETE** | From DHIS2 2.40 | +| **SCHEDULEEVENT** | From DHIS2 2.43 | +| **CREATEEVENT** | Not executed | + +In the **Server effects** dialog, a row for an action your server does not execute is dashed and dimmed, with the note "Not executed by this server (requires 2.43)" or "Not executed by this server". The row is there for reference only. + +:::note + +If the app cannot read the server version, it treats the server as DHIS2 2.40. ::: + +### Notifications stay Simulated + +The dry run does not report notifications. **SENDMESSAGE** and **SCHEDULEMESSAGE** rows in the **Server effects** dialog keep the **Simulated** tag even after **Verify with server**, and the dialog footer says so. A **Simulated** notification row means the browser engine fired the rule. It does not confirm that the server would send the message. + +Rule errors and warnings, mandatory fields and assignments do come back from the dry run. When the browser and the server both produced the same effect for the same rule, the row is tagged **Server-verified**. See the [provenance tags](../reference/provenance-tags.md). + +### Different inputs + +**Verify with server** sends exactly what a save would send. That is not the same as what the browser engine evaluates: + +- **Values of hidden fields are left out.** The payload drops the values of fields a rule hid, and empty values. A server rule that reads a hidden field does not see its value. +- **A stage form sends its event on its own.** In a tracker program, verifying a stage form sends that one event, without its enrollment, tracked entity or the other events. In the browser the same form sees the enrollment's attributes and the other events. The server can also reject the bare event with errors that are not about rules, listed under **Other import errors**. `TODO(verify)`: the exact server response for a stage event sent this way. +- **The Enrollment form sends no events.** Verifying the **Enrollment form** sends the tracked entity and its enrollment only. The server sees no event values in this case. +- **Stage events are dated today.** Every event in a tracker program gets today's date, whatever the **Enrollment date** in the context bar says. Rules that use event dates, or that compare one event with the previous one, can behave differently from real data entry. +- **Your account is the user.** In the browser, rules on user groups or roles evaluate against the account you are logged in with. In a dry run, DHIS2 is expected to evaluate them against the importing user, which is the same account. This has not been checked. + +See [Rule inputs](./rule-inputs.md) for the full list of what the browser engine uses. + +### "Out of scope" rules that still fire + +This difference is inside the browser, but it often looks like a mismatch. In a tracker program, a rule with no program stage is evaluated in every stage form, and it can fire there. The **Rules** tab of a stage form still labels it **Out of scope**, because its scope is the enrollment, and the "firing" count in the panel header leaves it out. Switch the panel to **All** to see it, and check the field badges and the **Trace** tab for its effects. + +```mermaid +flowchart TB + A[Same form values] --> B[Browser engine: all values, enrollment and other events] + A --> C[Dry run payload: hidden values dropped, one event or one enrollment] + B --> D[Effects on the form and Simulated rows] + C --> E[Server report: Server-verified and Server only rows] +``` + +## Why it matters + +- Treat the browser result as the answer to "what does this rule do with these values". Treat **Verify with server** as the answer to "would the server accept this payload". +- When a row says **Server only**, the server evaluated something the browser did not. Check the inputs above before you change the rule. +- When a notification or scheduled event matters, check its row in the **Server effects** dialog and remember that the dry run cannot confirm it. + +## Related pages + +- [How program rules are evaluated](./how-program-rules-are-evaluated.md) +- [Rule inputs](./rule-inputs.md) +- [Check rules against the server](../using-the-app/check-rules-against-the-server.md) +- [Preview server effects](../using-the-app/preview-server-effects.md) +- [Provenance tags](../reference/provenance-tags.md) +- [DHIS2 version compatibility](../introduction/dhis2-version-compatibility.md) diff --git a/docs/help/report-a-bug.md b/docs/help/report-a-bug.md index 6e5995c..33b7800 100644 --- a/docs/help/report-a-bug.md +++ b/docs/help/report-a-bug.md @@ -1,15 +1,65 @@ --- title: 'Report a bug' -description: 'Explains where to report a problem: the app repository or dhis2-form-utils.' +description: 'Explains where to report a problem, in the app repository or in dhis2-form-utils, and what to include.' sidebar_position: 2 --- # Report a bug -This page explains where to report a problem: the app repository or dhis2-form-utils. +## Goal -:::info Draft +Report a problem so it reaches the people who can fix it, with enough detail to reproduce it. -This page is a stub. The content is coming in a later release of the docs. +## Before you start -::: +- Check [Troubleshooting and FAQ](./troubleshooting-and-faq.md). Many problems are about access or organisation units, and some are known limitations. +- You need a GitHub account to open an issue. +- Do not include passwords, usernames, or personal or patient data, in the text or in screenshots. + +## Steps + +1. Decide where the problem belongs, using the list under [App or rule engine](#app-or-rule-engine-how-to-tell-which). If you are not sure, use the app repository. +2. For the app, open [a new issue in the program-rules-playground repository](https://github.com/nnkogift/program-rules-playground/issues/new). You can also get there from the app: on the program list, select **About** at the bottom of the page, then **Report a bug**. +3. Choose a form: + - **Report a problem**, when something in the app does not work the way you expected. + - **Suggest an improvement**, for an idea that would make the app easier or more useful. +4. For the rule engine or the rules panel, open [an issue in the dhis2-form-utils repository](https://github.com/nnkogift/dhis2-form-utils/issues) instead. +5. Fill in the details listed under [What to include](#what-to-include), and submit the issue. + +### App or rule engine: how to tell which + +Report it in **program-rules-playground** when the problem is in: + +- The program list, searching for a program, or opening one. +- The context bar: the organisation unit picker, the date, or **Reset playground**. +- The page layout: the enrollment rail, adding events, the form buttons, the **About** page. +- **Validate form**, **Verify with server** or **Preview on-complete effects**, including what is sent to the server and how its results are shown on the form. + +Report it in **dhis2-form-utils** when the problem is in: + +- The result of a rule: it fires when it should not, does not fire, or assigns the wrong value, compared with the same values in a DHIS2 data entry app. +- The rules panel: the **Rules**, **Trace** or **Graph** tab. +- The **Server effects** dialog or the program rule details dialog. +- How a field renders or validates its value, for example a date, an option set or a coordinate field. + +The app's issue chooser also links to the dhis2-form-utils issues, under "Report a rule engine or form library bug (developers)", and to the DHIS2 community for general questions about DHIS2 or program rules. + +### What to include + +- **DHIS2 version**, for example 2.43.2. `TODO(verify)`: where users find the DHIS2 version on 2.40 to 2.43. +- **App version**. On the program list, select **About** at the bottom of the page and copy the **Version**. +- **Program**: its name, and its ID if you can share it. The program list shows the ID under each program name. +- **Steps**: what you did, in order, and the values you entered. "Open the program, enter 150 in Number input, select **Verify with server**" is enough. +- **What you expected and what happened**, with the exact text of any message. +- **Screenshots**, especially of the **Trace** tab with the relevant evaluation expanded, so the changed fields and the rules that fired are visible. For a rule result, a screenshot of the **Rules** tab or of the program rule details helps too. +- **Browser** and its version. + +## What you'll see + +GitHub creates the issue with a `[Problem]:` or `[Suggestion]:` title prefix. Maintainers may ask you for more details in the issue, so keep an eye on your GitHub notifications. + +## Related pages + +- [Troubleshooting and FAQ](./troubleshooting-and-faq.md) +- [Find out why a rule did or didn't fire](../using-the-app/find-out-why-a-rule-did-or-didnt-fire.md) +- [Release notes](./release-notes.md) diff --git a/docs/help/troubleshooting-and-faq.md b/docs/help/troubleshooting-and-faq.md index 821152e..b6a6559 100644 --- a/docs/help/troubleshooting-and-faq.md +++ b/docs/help/troubleshooting-and-faq.md @@ -1,15 +1,129 @@ --- title: 'Troubleshooting and FAQ' -description: 'Collects common problems and questions, with fixes.' +description: 'Fixes for common problems: organisation units, programs that do not open, Verify with server errors, missing authorities, and known limitations.' sidebar_position: 1 --- # Troubleshooting and FAQ -This page collects common problems and questions, with fixes. +Find the message or the symptom you see, then follow the fix. For the full list of messages the app shows, see [Messages and errors](../reference/messages-and-errors.md). -:::info Draft +## Organisation units -This page is a stub. The content is coming in a later release of the docs. +### "No organisation units available" + +The program has no organisation units assigned. The app checks only the program's own assignment, and it does not show the forms at all in this case. + +To fix it, assign at least one organisation unit to the program in the Maintenance app (DHIS2 2.40 to 2.42) or in Metadata Management (DHIS2 2.43), then reload the app. + +### "Could not load organisation units" + +The full message is "The organisation units for this program could not be loaded for data entry." The app could not read your own organisation units or the program's organisation units from the server, and it does not show the forms. + +Reload the page. If it keeps happening, check that you are still logged in to DHIS2 and that the server is reachable. If the problem continues, [report a bug](./report-a-bug.md). + +### The organisation unit tree is empty + +**Known issue.** If your user's organisation units are below national level, for example a district or a facility, the **Select organisation unit** dialog shows an empty tree, even when you search. Only the text "Only organisation units assigned to this program can be selected." is shown. Users with a national-level organisation unit are not affected. + +Without an organisation unit you cannot use **Verify with server**. Everything else still works: you can fill in the forms, watch the rules, use **Validate form**, **Preview server effects** and **Preview on-complete effects**. + +A fix is planned. Until it ships, use a DHIS2 user whose organisation unit is at national level (the top level of the hierarchy) when you need **Verify with server**. `TODO(verify)`: any other workaround, for example assigning the user's own organisation unit to the program. + +### "Required to verify or save" under the organisation unit + +You selected **Validate form**, **Verify with server**, **Preview server effects** or **Preview on-complete effects** before choosing an organisation unit. The message is a reminder, nothing is saved. Only **Verify with server** actually needs the organisation unit, and without one it fails with "Could not verify with server" and "Select an organisation unit before saving or verifying". + +Use the **Select** button next to **Organisation unit** in the context bar and pick an organisation unit. See [Set the organisation unit and date](../using-the-app/set-the-org-unit-and-date.md). + +## Programs + +### A program is missing from the list + +The program list shows only the programs you can read. If you do not have metadata read access to a program, it is left out without any message. Ask an administrator to share the program with you (metadata: can view). + +### "Program not found" + +The app could not find the program, or you do not have metadata read access to it. This also happens when you open a link to a program that was deleted or that is shared with other users only. + +Select **Back to programs**, search for the program, and open it from the list. If it is not in the list, see the previous question. + +### "Could not load this program. Try again later." + +The program metadata request failed for another reason, for example a network problem or a server error. Reload the page. If it keeps happening, [report a bug](./report-a-bug.md) and include the time it happened. + +## Verify with server + +### "Could not verify with server" + +The dry run did not return a validation report. The message under it says why: + +- "Select an organisation unit before saving or verifying": select an organisation unit in the context bar and try again. +- A message from DHIS2: the server rejected the request. Check that you are still logged in. +- "An unexpected error occurred": the request failed without a message. Try again, and [report a bug](./report-a-bug.md) if it keeps happening. + +Nothing is retried automatically. Select **Verify with server** again to rerun it. + +### "Server check found issues" with an error code + +Errors that are not produced by a program rule are listed under **Other import errors**, each with its DHIS2 error code. The common ones are about your access, not about the rules: + +| Code | What it means | What to do | +| --- | --- | --- | +| `E1000` | The organisation unit you selected is not in your data capture organisation units. | Pick an organisation unit you can capture data for, or ask an administrator to add it to your user's data capture organisation units. | +| `E1091` | You cannot write data for this program. | Ask an administrator to give you data write access to the program (data: can capture). | +| `E1095` | You cannot write data for this program stage. | Ask for data write access to the program stage. | +| `E1001` | You cannot write data for the tracked entity type (tracker programs). | Ask for data write access to the tracked entity type. | +| `E1029`, `E1041` | The organisation unit you selected is not assigned to the program. | Pick an organisation unit that is assigned to the program. Unassigned parents in the tree are greyed out and cannot be selected. | +| `E1096`, `E1104` | You have no data read access that the import needs. | Ask an administrator for data read access to the program and, for tracker programs, to the tracked entity type. | +| `E1099` | You cannot write data for the category option. | Ask an administrator to give you data write access to the category option, usually the default one. | + +Your user needs no special authority for **Verify with server**, only these sharing and organisation unit settings. See [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md). + +:::note + +These results were checked on DHIS2 2.43.2. `E1000`, `E1029` and `E1041` were observed. `E1091`, `E1095`, `E1001`, `E1096`, `E1104` and `E1099` are the messages DHIS2 2.43 defines for these cases and were not reproduced. `TODO(verify)`: the codes on DHIS2 2.40 to 2.42. ::: + +## Access to the app + +### The app is not in the apps menu, or you see "Unable to find an app for this URL" + +Your user role does not include the app. DHIS2 shows "Something went wrong" with "Unable to find an app for this URL." and a **Return to home page** link. + +Ask an administrator to add the Program Rules Playground app to one of your user roles, in the Users app under **Apps**. The authority is expected to be named `M_programrulesplayground`. `TODO(verify)`: the authority name after installing the app. Users with the `ALL` authority always see the app. + +### "Edit in Metadata Management app" opens "Unable to find an app for this URL" + +The rule details dialog links to the app where you edit program rules. On DHIS2 2.43 that is Metadata Management, on 2.40 to 2.42 the Maintenance app. If your role does not include that app, DHIS2 shows the same "Unable to find an app for this URL." page. Ask for access to the app, and for the program rule authorities if you also need to edit rules there. See [Open and edit a rule](../using-the-app/open-and-edit-a-rule.md). + +## Known limitations + +### A HIDEPROGRAMSTAGE rule has no visible effect + +The app does not hide program stages. When a **HIDEPROGRAMSTAGE** rule fires, it appears in the **Rules**, **Trace** and **Graph** tabs, but the stage stays in the rail and you can still open it. Use the **Trace** tab to check that the rule fires. + +### A warning or error does not show the value from the rule + +For **SHOWWARNING**, **SHOWERROR**, **WARNINGONCOMPLETE** and **ERRORONCOMPLETE** on a field, the text under the field shows only the rule action's static text. The evaluated value from the action's data expression is not added. For example, a rule with the text "Number exceeds 100: " and the value of the field as data shows "Number exceeds 100:" without the number. On-complete messages that are not attached to a field do include the value in the completion banner. + +## FAQ + +### Does the app save anything? + +Not from version 0.1.0-alpha.10. From that version, the only request that sends form data is **Verify with server**, which uses `importMode=VALIDATE`, a dry run, apart from files chosen in file or image fields, which upload at once. Versions 0.1.0-alpha.9 and earlier save real data when you select **Save event** or **Register tracked entity**, so upgrade if you still run one. See [Is it safe on production?](../introduction/is-it-safe-on-production.md). + +### Why is a rule firing but labelled "Out of scope"? + +In a tracker program, rules without a program stage belong to the enrollment, but they are also evaluated in stage forms. The stage form's **Rules** tab labels them **Out of scope** even when they fire. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md). + +### Why does a notification stay "Simulated" after Verify with server? + +The dry run does not report notifications, so the app cannot confirm them. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md). + +## Related pages + +- [Messages and errors](../reference/messages-and-errors.md) +- [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md) +- [Report a bug](./report-a-bug.md)