diff --git a/docs/using-the-app/check-rules-against-the-server.md b/docs/using-the-app/check-rules-against-the-server.md index cc6ec34..31fc664 100644 --- a/docs/using-the-app/check-rules-against-the-server.md +++ b/docs/using-the-app/check-rules-against-the-server.md @@ -1,15 +1,79 @@ --- title: 'Check rules against the server' -description: 'Shows how to use Verify with server to compare your input against what the DHIS2 server reports.' +description: 'Shows how to use Verify with server to run a dry run on your DHIS2 server and compare its rule results with the playground.' sidebar_position: 9 --- # Check rules against the server -This page shows how to use **Verify with server** to compare your input against what the DHIS2 server reports. +## Goal -:::info Draft +Find out what your DHIS2 server says about the values in a form. **Verify with server** sends the form to the server as a dry run. The server runs its own program rules and validation, reports what it found, and saves nothing. -This page is a stub. The content is coming in a later release of the docs. +Use it when you want to compare what the server reports with what the playground shows. -::: +## Before you start + +- Select an **Organisation unit** in the context bar. **Verify with server** is the only form action that needs one. See [Set the organisation unit and date](./set-the-org-unit-and-date.md). +- Make sure your user can capture data for the program in that organisation unit. The server checks your sharing and capture scope during the dry run. See [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md). + +## Steps + +1. Fill in the form. +2. Select **Verify with server**. The button shows a spinner while the server works. +3. Read the notice above the form buttons, and look for errors on the fields. +4. Change values and select **Verify with server** again to run a new check. There is no automatic retry. + +## What you'll see + +![Server check passed after Verify with server](./img/verify-with-server.png) + +### The notice + +| Notice | What it means | +| --- | --- | +| **Server check passed**, "Server found no rule errors or warnings." | The dry run returned no rule errors, no rule warnings and no other import errors. | +| **Server check found issues**, "The affected fields are highlighted in the form." | The server raised rule errors, and each one is shown on the field it targets. | +| **Server check found issues**, with a list | Some results could not be shown on a field: warnings, results with no target field, or results for a field that isn't on screen. Each line shows the field name (a link that jumps to the field) and the server's message. | +| **Other import errors (n)** | Shown inside **Server check found issues** when the server rejected the payload for reasons that are not program rules, such as sharing, capture scope or an invalid value. Each error shows its DHIS2 error code. | +| **Could not verify with server** | The dry run did not complete. The notice shows the DHIS2 error message, or "An unexpected error occurred". | + +When the server returns no rule errors, you see **Server check passed**, even if the playground shows a rule error on a field. Finding differences like this is what **Verify with server** is for. See [Why client and server results differ](../concepts/why-client-and-server-results-differ.md). + +### Rule errors on fields + +When the server reports a rule error for a field that is on screen, the error appears on that field, like a field error. The next time you select **Verify with server**, the app clears these errors before it runs the new check. + +The app recognises the server's rule messages for errors, warnings, mandatory fields, assigned values and scheduled events. An assigned value that the server would overwrite shows as "Assign overwrite" in the [Server effects](./preview-server-effects.md) dialog. + +### Running it again + +- While a new check runs, the old notice disappears. +- If the new check fails with **Could not verify with server**, the notice shows only the failure. Field errors from the earlier check are already cleared. +- The last result that completed is kept. The **Server effects** dialog keeps comparing against it, so its provenance tags don't reset when a retry fails. + +### What the app sends + +The app sends exactly the payload a save would send, as `POST /api/tracker?importMode=VALIDATE&async=false`. `importMode=VALIDATE` makes it a dry run: the server checks the payload and discards it. Fields hidden by a rule and empty fields are left out. + +| Form | Payload | +| --- | --- | +| Event program form | One event: program, program stage, organisation unit, the **Event date** as the event date, status and data values. | +| Enrollment form | One tracked entity with its attributes and one enrollment (program, organisation unit, status `ACTIVE`, the **Enrollment date**, and the incident date when the program shows one). No events are sent. | +| Stage form in a tracker program | One event on its own, with no tracked entity or enrollment. The event date is today. | + +`TODO(verify)`: how the server responds to the bare stage event. It may answer with **Other import errors** that are not about your rules. + +The event status is `ACTIVE`. After you open the **Server effects** dialog for completion, through **Preview on-complete effects** or **Complete anyway**, the form sends `COMPLETED` with a completion date, so the server also runs its on-complete rules. Select **Preview server effects** to switch back to `ACTIVE`. See [Test on-complete rules](./test-on-complete-rules.md). + +### Without an organisation unit + +If you select **Verify with server** with no organisation unit, the **Organisation unit** field shows "Required to verify or save", and the notice shows **Could not verify with server** with "Select an organisation unit before saving or verifying". Select an organisation unit and try again. Nothing is saved, even though the messages say "save". + +## Related pages + +- [Preview server effects](./preview-server-effects.md) +- [Why client and server results differ](../concepts/why-client-and-server-results-differ.md) +- [Requirements and user authorities](../getting-started/requirements-and-user-authorities.md) +- [Messages and errors](../reference/messages-and-errors.md) +- [Troubleshooting and FAQ](../help/troubleshooting-and-faq.md) diff --git a/docs/using-the-app/preview-server-effects.md b/docs/using-the-app/preview-server-effects.md index 093fefa..14b856e 100644 --- a/docs/using-the-app/preview-server-effects.md +++ b/docs/using-the-app/preview-server-effects.md @@ -1,15 +1,72 @@ --- title: 'Preview server effects' -description: 'Shows how to use Preview server effects to see notifications and scheduled events without sending anything.' +description: 'Shows how to use Preview server effects to see the notifications and scheduled events your rules would trigger on the server, without sending anything.' sidebar_position: 10 --- # Preview server effects -This page shows how to use **Preview server effects** to see notifications and scheduled events without sending anything. +## Goal -:::info Draft +See what the DHIS2 server would do when this form is saved: the notifications it would send or schedule, and the events it would schedule. Some rule actions only run on the server, so the form itself never shows them. **Preview server effects** lists them in a read-only dialog called **Server effects**. Nothing is sent. -This page is a stub. The content is coming in a later release of the docs. +## Before you start + +- Open a program and a form. **Preview server effects** works without an organisation unit. +- To compare the preview with the server, run [Verify with server](./check-rules-against-the-server.md) first. + +## Steps + +1. Fill in the form so the rules you want to test fire. +2. Select **Preview server effects**. In a tracker program it is on the Enrollment form and on every stage form. +3. Read the **Server effects** dialog. +4. Select a rule name to open its details. +5. Select **Close** to return to the form. + +## What you'll see + +![Server effects dialog with a notification row and its provenance tag](./img/server-effects-summary.png) + +The dialog loads the server-side actions of the program's rules, showing "Loading server-side actions…" while it works. It then lists what fired in the latest evaluation of the form, in up to three sections: + +- **Notifications (n)**: one row per **SENDMESSAGE** or **SCHEDULEMESSAGE** action. A row shows the **Template**, **Recipient**, **Delivery channels**, **Subject** and **Message**. A scheduled message also shows **Scheduled for**, the date the rule worked out. If that date isn't a valid date, the row adds the tag "Invalid date, server will skip". In the subject and message, placeholders that point at a field with a value are filled in from the form, including Enrollment form attributes when you preview a stage form. Placeholders the app can't fill in, such as `V{program_name}`, stay as code. If the template is missing, the row says "Notification template not found for this action." +- **Events (n)**: one row per **SCHEDULEEVENT** or **CREATEEVENT** action, with the **Target stage** and **Due date**. +- **Server validation (n)**: after a [Verify with server](./check-rules-against-the-server.md) run, the rule errors, warnings and assigned-value overwrites the server reported. Each row shows the level (**Error**, **Warning** or **Assign overwrite**), the rule and "field: message". + +If nothing server-side fired, the dialog says "No server-side rule effects fired." + +Each row names its rule. Select the name to open the rule's details. + +### Provenance tags + +The tag on the right of each row says where the row comes from: + +| Tag | Meaning | +| --- | --- | +| **Simulated** | The playground worked this out in your browser. There is no server result to compare it with. | +| **Server-verified** | Your browser and the server's dry run both produced it. | +| **Server only** | The server's dry run reported it, but the playground didn't produce it. | + +A row that the server you are connected to would not run is dashed and dimmed, with the note "Not executed by this server" or "Not executed by this server (requires 2.43)". See [Provenance tags](../reference/provenance-tags.md). + +### Why notifications stay Simulated + +The dry run doesn't report notifications. So even after **Verify with server**, notification rows keep the **Simulated** tag. The dialog footer says so: "The dry run doesn't report notifications, so notification rows stay Simulated." Before any dry run, the footer says "Use Verify with server on the form to compare against the server." + +:::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. ::: + +### Event status + +**Preview server effects** previews the form with status `ACTIVE`. To preview what happens when the event is completed, use **Preview on-complete effects**. See [Test on-complete rules](./test-on-complete-rules.md). + +## Related pages + +- [Check rules against the server](./check-rules-against-the-server.md) +- [Test on-complete rules](./test-on-complete-rules.md) +- [Provenance tags](../reference/provenance-tags.md) +- [Rule action types](../reference/rule-action-types.md) +- [Why client and server results differ](../concepts/why-client-and-server-results-differ.md) diff --git a/docs/using-the-app/test-on-complete-rules.md b/docs/using-the-app/test-on-complete-rules.md index b2e365e..796e9d9 100644 --- a/docs/using-the-app/test-on-complete-rules.md +++ b/docs/using-the-app/test-on-complete-rules.md @@ -1,15 +1,66 @@ --- title: 'Test on-complete rules' -description: 'Shows how to use Preview on-complete effects and the completion pass to test rules that run when you complete a form.' +description: 'Shows how to use Preview on-complete effects and the completion pass to test the rules that run when an event is completed.' sidebar_position: 11 --- # Test on-complete rules -This page shows how to use **Preview on-complete effects** and the completion pass to test rules that run when you complete a form. +## Goal -:::info Draft +Test the rules that only matter when an event is completed: **ERRORONCOMPLETE**, **WARNINGONCOMPLETE** and required fields. **Preview on-complete effects** runs a completion pass, the same check a data entry app runs before it lets you complete an event. It then shows the server effects for a completed event. Nothing is completed or saved. -This page is a stub. The content is coming in a later release of the docs. +## Before you start -::: +- Open an event program form or a stage form in a tracker program. The Enrollment form has no **Preview on-complete effects** button. +- You don't need an organisation unit, unless you also want to run **Verify with server**. + +## Steps + +1. Fill in the form. A field that a rule flags on completion already shows an **On complete: error** or **On complete: warning** badge. +2. Select **Preview on-complete effects**. +3. If the completion pass finds nothing, the **Server effects** dialog opens for a completed event. See [Preview server effects](./preview-server-effects.md). +4. If it finds issues, read the banner above the form buttons, then choose: + - **Back to editing** to close the banner and go back to the form. + - **Complete anyway** to open the **Server effects** dialog for a completed event. This button only appears when nothing blocks completion. +5. To check the completed event with the server too, close the **Server effects** dialog, then select **Verify with server**. After the dialog has been opened for a completed event, **Verify with server** sends the event as completed. + +## What you'll see + +### The completion pass + +The app sets the form's status to completed, waits for the rules to evaluate again, and collects: + +- **Error**: an **ERRORONCOMPLETE** action on a visible field, or one with no field. +- **Required**: a visible field that is required, by metadata or by a rule, and is empty. +- **Warning**: a **WARNINGONCOMPLETE** action. + +### The completion banner + +![Cannot complete this event yet banner raised by an on-complete error rule](./img/completion-banner.png) + +| Banner | When | Buttons | +| --- | --- | --- | +| **Cannot complete this event yet** | At least one error or empty required field. | **Back to editing** | +| **Review before completing** | Only warnings. | **Back to editing**, **Complete anyway** | + +Blocking issues are listed first. Each line reads "Kind: field – message", for example "Error: Number input – 99 blocks completion" or, after you type `mandatory` in **Trigger text** of the PRT event program, "Required: Mandatory target – This field is required". Select the field name to jump to the field. Keyboard focus moves to the banner when it appears. + +The banner updates as you fix fields. When the last issue is gone, the banner disappears. While the banner is open, **Preview on-complete effects** is disabled. + +### What Complete anyway does + +The playground saves nothing, so **Complete anyway** doesn't complete the event. It opens the **Server effects** dialog with the status set to completed, so you can see what the server would do on completion despite the warnings. When you close the dialog, the form goes back to its normal status and the banner closes. + +After you have opened the dialog this way, **Verify with server** sends the event with status `COMPLETED` and a completion date, so the server runs its own on-complete checks. Select **Preview server effects** to switch the dry run back to `ACTIVE`. + +### On-complete messages on fields + +While the form is in completed status, a field with an on-complete message also shows a dashed note under it, "On complete:" followed by the message. + +## Related pages + +- [Preview server effects](./preview-server-effects.md) +- [Check rules against the server](./check-rules-against-the-server.md) +- [Read field badges and hidden-field placeholders](./read-field-badges-and-hidden-field-placeholders.md) +- [Effect badges legend](../reference/effect-badges-legend.md) diff --git a/docs/using-the-app/validate-a-form.md b/docs/using-the-app/validate-a-form.md index 8954edb..dc2a2fd 100644 --- a/docs/using-the-app/validate-a-form.md +++ b/docs/using-the-app/validate-a-form.md @@ -1,15 +1,54 @@ --- title: 'Validate a form' -description: 'Shows how to run Validate form and read its result.' +description: 'Shows how to run Validate form, read the issue summary and jump to the fields that need attention.' sidebar_position: 8 --- # Validate a form -This page shows how to run **Validate form** and read its result. +## Goal -:::info Draft +Check the values you entered against the form's own field rules before you test anything against the server. **Validate form** runs in your browser and sends nothing. -This page is a stub. The content is coming in a later release of the docs. +## Before you start -::: +- Open a program and the form you want to check. See [Find and open a program](./find-and-open-a-program.md). +- Enter some values. You don't need an organisation unit for this check. + +## Steps + +1. Fill in the form as you want to test it. +2. Select **Validate form** under the fields. +3. Read the notice that appears above the form buttons. +4. If the notice lists fields, select a field name to jump to it, fix the value, and select **Validate form** again. + +## What you'll see + +**Validate form** checks every field in the form against its metadata only: + +- the value type, for example a number, a date or a phone number +- whether the field is compulsory in the metadata +- whether the value is one of the field's options +- any minimum or maximum the field has + +It checks fields that a rule hid, too. It does not use the results of your program rules: a field that shows a rule error (a **SHOWERROR** action) and an empty field that a rule made mandatory (a **SETMANDATORYFIELD** action) don't count as issues. To see those, look at the field badges and the text under each field, see [Read field badges and hidden-field placeholders](./read-field-badges-and-hidden-field-placeholders.md), or check the **Rules** tab of the rules panel, see [Find out why a rule did or didn't fire](./find-out-why-a-rule-did-or-didnt-fire.md). + +The form also checks a field when you leave it, so you may see field errors before you select **Validate form**. + +![Validate form notice above the form buttons](./img/validate-form.png) + +The notice shows one of three results: + +| Notice | What it means | +| --- | --- | +| **Form is valid**, "No validation issues were found." | Every field passed. | +| **Form has issues** | One or more fields failed a metadata check. The notice lists them by label, each as a link. Selecting a link scrolls to the field and puts the cursor in it. Keyboard focus moves to the notice when it appears. | +| **Could not validate the form** | The check itself failed. The notice shows the error message. | + +If you haven't selected an organisation unit, the **Organisation unit** field in the context bar shows "Required to verify or save". This is only a reminder for **Verify with server**. **Validate form** still runs. + +## Related pages + +- [Check rules against the server](./check-rules-against-the-server.md) +- [Read field badges and hidden-field placeholders](./read-field-badges-and-hidden-field-placeholders.md) +- [Messages and errors](../reference/messages-and-errors.md)