diff --git a/docs/manage-projects/notifications.md b/docs/manage-projects/notifications.md new file mode 100644 index 00000000000..e6d67fae83c --- /dev/null +++ b/docs/manage-projects/notifications.md @@ -0,0 +1,28 @@ +--- +title: Failure Notifications and Digests +sidebar_label: Notifications +--- + +If you would like to receive email `Notifications` when a Workflow Run fails or +emailed summary `Digests` on activity across your project, read on to learn how +to configure your project settings accordingly. + +## How to turn on email notifications for Run failures + +1. Go to your Project `Settings` > `Collaboration` page +2. Find your User +3. In the `Failure Alert` dropdown, choose `Enabled` to turn on real-time email + notifications for Run failures + +![Notifications Config](/img/notifications.png) + +## How to turn on email notifications for Run failures + +1. Go to your Project `Settings` > `Collaboration` page +2. Find your User +3. In the `Digest` dropdown, choose desired notification frequency (`Daily`, + `Weekly`,`Monthly`, or `Never` ) if you would also like to receive a summary + of Work Order activity and success rates across your project. See below + screenshot for an example digest. + +![Digest Email](/img/digest_email.png) diff --git a/docs/monitor-history/activity-history.md b/docs/monitor-history/activity-history.md index 9c9d1031e55..e5e9eed76e8 100644 --- a/docs/monitor-history/activity-history.md +++ b/docs/monitor-history/activity-history.md @@ -1,9 +1,40 @@ --- -title: Activity History Overview -sidebar_label: Activity History +title: History tracking in OpenFn +sidebar_label: History --- -:::warning Under construction -This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)". +For platform administrators, `History` is your central console for monitoring +all activity across your active Workflows. Read on to understand its key +components. -::: \ No newline at end of file +## History + +The `History` page provides a list of all of the +[Work Orders](/documentation/next/get-started/terminology#work-order) and +[Runs](/documentation/next/get-started/terminology#run) that have been processed +in a Project. + +![History](/img/case-referral-history.png) + +## Workflow execution: Work Orders and Runs + +OpenFn Workflows are executed as follows: + +1. A Workflow `Trigger` is activated by a webhook event, cron timer, or manual + action. +2. This creates a `Work Order`--a request to run a Workflow with a given input + (e.g, a new form submission or patient record that needs to be processed). + For a Work Order to be cpmpleted, it should reach an ending Step succesfully + (without errors) - this ensures that the processing of has been completed. +3. A `Run` is then executed to try to complete the Workflow successfully. This + Run will have a + [status code](/documentation/next/monitor-history/status-codes), indicating + whether the Workflow Steps were successfully processed. +4. If the 1st `Run` fails, then you can rerun it to "retry" the workflow. A 2nd + `Run` will be created. If successful, then both the Run and related Work + Order will be updated with a `success` status. + +![History Page](/img/history-page-annotated.png) + +Check out the other pages in this docs section to learn more about inspecting +Runs, troubleshooting, and rerunning failed Runs. diff --git a/docs/monitor-history/failure-notifications-digests.md b/docs/monitor-history/failure-notifications-digests.md deleted file mode 100644 index 2f4907cfd6b..00000000000 --- a/docs/monitor-history/failure-notifications-digests.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Failure notifications and Digests -sidebar_label: Failure notifications and Digests ---- - - - -On the `Collaboration` page of your project settings, you can turn on notifications to receive email alerts when a job fails. You can also subscribe to digests that summarize project activity including the number of `Work Orders` that were processed correctly and the number that failed. - - - diff --git a/docs/monitor-history/inspect-runs.md b/docs/monitor-history/inspect-runs.md new file mode 100644 index 00000000000..71029f193b4 --- /dev/null +++ b/docs/monitor-history/inspect-runs.md @@ -0,0 +1,29 @@ +--- +title: Inspect Runs & Search via the History page +sidebar_label: Inspect Runs +--- + +A [Run](/documentation/next/get-started/terminology#run) is created each time +OpenFn attempts to excute a Workflow for a given Work Order. All Runs can be +viewed, filtered, and searched via the `History` page. + +In short, Runs tell us "what happened" when OpenFn tried to execute the +Workflow. Runs have start times, end times, logs, and +[status codes](/documentation/next/monitor-history/status-codes) that indicate +when they took place, what they did, and whether or not they succeeded. + +## Inspect Runs + +Check out the below video tutorial +([or see link](https://youtu.be/xPgVZmJMT3w?si=bMf9wof_Qla-0ihW)) for a walk +through on inspecting Runs via the History page. + + + +## Search History and Runs + +To learn how to search and filter Work Order and Run history via the History +page, check out the below video tutorial +([or see link](https://youtu.be/XIUykmLCxwQ?si=pCzefw4zyLxG1voE)). + + diff --git a/docs/monitor-history/rerunning-workflow.md b/docs/monitor-history/rerunning-workflow.md index e10739bb044..d926afb628b 100644 --- a/docs/monitor-history/rerunning-workflow.md +++ b/docs/monitor-history/rerunning-workflow.md @@ -1,8 +1,42 @@ --- -title: Re-running your workflows -sidebar_label: Re-running your workflows +title: Rerun after failures & Workflow edits +sidebar_label: Rerun failures --- -Did a step in your workflow fail? Looking to resync historical data? Whatever the reason, you can re-run your OpenFn workflow from the History page or the Inspector view. Check out the video below for a how-to. +Did a step in your workflow fail? Looking to resync historical data? Whatever +the reason, watch the below video tutorial +([or see link](https://youtu.be/DvLRA6kloNE?si=U0NMx-HsCMZxeJwg)) to learn how +to rerun your Workflow. -Video tutorial: [Re-running your workflows](https://www.loom.com/share/281a1f8bbc8547078d52e5c03df65a96?sid=c212a374-1343-4d0f-8ed8-e30642a12695). \ No newline at end of file + + +## Rerun via History page + +To rerun your Workflow from the `History` page: + +1. Locate your failed `Work Order` (use the search bar or filters, if needed) +2. Collapse the Work Order to view related `Runs` +3. Click `rerun` next to the Step that you want to rerun the workflow from. + Choose the first step to start from the beginning, or a later step to rerun + the workflow from that step onwards. +4. This will create a new `Run` related to the same Work Order. Check the + `Status` to see if this Run successfully completed the Work Order. + +## Rerun via Inspector view + +To rerun your Workflow from the `Inspector` page: + +1. Locate your failed `Work Order` (use the search bar or filters, if needed) +2. Collapse the Work Order to view related `Runs` +3. Click `inspect` next to the Step that you want open up in the `Inspector` + view for further troubleshooting. +4. This will open up the `Inspector` view so that you can see the `Input` and + `Output` of the failed Step. You can make edits to the custom logic, as + needed, in the `Editor` panel. +5. When ready to retry the workflow against the same Input, click + `Rerun from here`. This will create a new `Run` for the same Work Order. Go + to `History` page to check the `Status` to see if this Run successfully + completed the Work Order. +6. If you prefer to create a _new_ Work Order (instead of retrying the same Work + Order), you can click the dropdown next to "Rerun from here" and _instead_ + choose `Create New Work Order`. diff --git a/docs/monitor-history/troubleshooting.md b/docs/monitor-history/troubleshooting.md index c7a81fa6038..5ec36b35a7b 100644 --- a/docs/monitor-history/troubleshooting.md +++ b/docs/monitor-history/troubleshooting.md @@ -9,7 +9,7 @@ sidebar_label: Troubleshooting One of the most helpful pages for troubleshooting on OpenFn is the [History](/documentation/next/monitor-history/activity-history) page. -This page provides a list of all of the runs executed for a Work Order and their status. Project administrators can troubleshoot errors by clicking into the run to review the run details. Learn more about runs [here](/documentation/next/monitor-history/viewing-workflow-runs) here. +This page provides a list of all of the runs executed for a Work Order and their status. Project administrators can troubleshoot errors by clicking into the run to review the run details. Learn more about runs [here](/documentation/next/monitor-history/inspect-runs) here. ### Status codes @@ -81,13 +81,13 @@ their error messages [here](/adaptors#connect-anything). ## Leveraging search and filtering in OpenFn -Leverage the various search functionalities in OpenFn to find the right runs to support your troubleshooting. You can search on the History page across OpenFn IDs, Inputs, and/or Logs. Check out this [video](https://www.loom.com/share/083b371a26de43cfbbb72321249a694b?sid=3e2a897b-81d5-487e-a7a4-f8a7b88c7b63) for how to use Search. +Leverage the various search functionalities in OpenFn to find the right runs to support your troubleshooting. You can search on the History page across OpenFn IDs, Inputs, and/or Logs. Check out this [video](https://youtu.be/XIUykmLCxwQ?si=hquc8rPTJrAZkbbD) for how to use Search. ## Sign up for email alerts -You can turn on notifications to receive [email alerts ](/documentation/next/monitor-history/failure-notifications-digests)when a workflow fails and subscribe to digests that summarize project activity. +You can turn on notifications to receive [email alerts](/documentation/next/manage-projects/notifications) when a workflow fails and subscribe to digests that summarize project activity. ## More diff --git a/docs/monitor-history/viewing-workflow-runs.md b/docs/monitor-history/viewing-workflow-runs.md deleted file mode 100644 index 94064bf4505..00000000000 --- a/docs/monitor-history/viewing-workflow-runs.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Viewing Workflow Runs -sidebar_label: Viewing Workflow Runs ---- - -A Run is each time OpenFn attempts to excute a Work Order. All runs are recorded on the History page. Check out the video below for more details! - -Video tutorial: [Viewing Workflow Runs](https://www.loom.com/share/0ebfeb5671274d739c55f08b6e218353?sid=b835d96a-b667-470b-b5be-675e2d699f03) - - diff --git a/sidebars-main.js b/sidebars-main.js index 24e5e79d7e3..e68379e5015 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -65,8 +65,7 @@ module.exports = { label: 'Monitor History', items: [ 'monitor-history/activity-history', - 'monitor-history/failure-notifications-digests', - 'monitor-history/viewing-workflow-runs', + 'monitor-history/inspect-runs', 'monitor-history/rerunning-workflow', 'monitor-history/troubleshooting', 'monitor-history/status-codes', @@ -80,6 +79,7 @@ module.exports = { 'manage-projects/retention-periods', 'manage-projects/io-data-storage', 'manage-projects/user-roles-permissions', + 'manage-projects/notifications', ], }, { diff --git a/static/img/digest_email.png b/static/img/digest_email.png new file mode 100644 index 00000000000..b40cf9e234b Binary files /dev/null and b/static/img/digest_email.png differ diff --git a/static/img/history-page-annotated.png b/static/img/history-page-annotated.png new file mode 100644 index 00000000000..52b4cb91c96 Binary files /dev/null and b/static/img/history-page-annotated.png differ