diff --git a/docs/build/workflow-snapshots.md b/docs/build/workflow-snapshots.md new file mode 100644 index 00000000000..a771df98380 --- /dev/null +++ b/docs/build/workflow-snapshots.md @@ -0,0 +1,63 @@ +--- +title: Workflow Snapshots +sidebar_label: Workflow Snapshots +slug: /workflow-snapshots +--- + +Workflow snapshots capture and store a state/version of a workflow (a combination of input, workflow configuration and job code) at a specific point in time when a workflow was updated or run. Snapshots are helpful with debugging, auditing, and improving overall workflow performance. + +### When is a snapshot made? +Snapshots are created in 2 ways: +1. When a user saves changes to their workflow either through the canvas or the Inspector +2. When a run is made either by creating a new work order or retrying a run + +### How can I view a snapshot? +To view a snapshot, go to the `History` page. Expand a work order to see the runs included. + +![Snapshot1](/img/snapshots1.png) + +From the expanded history view, there are two ways to visualize snapshots: +1. By inspecting a step in the run +2. From the Run view + +#### Viewing a snapshot by inspecting a step in the run + +Click on the inspect icon in front of the step you would like to view. + +![Inspect](/img/inspect.png) + +This will open the [inspector screen](../build/steps/step-editor.md) for that step in the run with all associated artifacts: logs and input/output data. On the inspector, you'll notice that you're in a read-only mode, and hovering on the workflow snapshot ID chip, you’ll see a message that reads “You are viewing a snapshot of this workflow that was taken on ….” + +![Snapshot2](/img/snapshots2.png) + +To view the corresponding canvas for this snapshot, close this inspector view by clicking the `X` on the top right corner of the page. This will open the associated canvas with the step selected as shown below. + +![Snapshot3](/img/snapshots3.png) + +From the canvas, you can inspect any step by clicking on the step and opening the inspector for the run associated with the step and snapshot. + +#### Viewing a snapshot from the Run view +From the expanded history view, click on the run ID to open the run view. + +![Snapshot4](/img/snapshots4.png) + +From this view, click on the Workflow name (Simple Flow) to open the workflow canvas for this snapshot. +Similar to viewing a snapshot by inspecting a step, you can click the inspect icon in front of the steps to open the inspector for the step. + +### Editing a Snapshot +Snapshots are read-only and serve as a reference for the state of a workflow when saved or a run is executed. As only the latest version can be edited, in order to edit the workflow you can click on the `Switch to latest version` on the canvas or use the toggle at the bottom right of the inspector page to switch to the latest version of the workflow. + +When you switch to the latest version, the snapshot ID tag will change to blue colour and the text will be `latest`. + +![Snapshot5](/img/snapshots5.png) + +![Snapshot6](/img/snapshots6.png) + +### Retrying a Snapshot +When retrying a run with a snapshot, the retry will be executed with the latest version of the workflow and job code. You cannot retry a workflow with an earlier snapshot, only with the latest version. + +### Snapshots and Version Control + +As they save a workflow as a particular set of configuration, input data and job code, snapshots are mainly tools to help administrators with auditing and dealing with errors (such as, for example, why a case hasn't been updated correctly in a database). + +OpenFn offers dedicated tools for [version control](../manage-projects/link-to-gh.md) that allows you and your team to manage changes in job code for faster and safer development, debugging and revision. \ No newline at end of file diff --git a/sidebars-main.js b/sidebars-main.js index 6be0a5b1713..99b23eb9a8d 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -67,6 +67,7 @@ module.exports = { 'build/editing-locally', 'build/working-with-branches', 'build/troubleshooting', + 'build/workflow-snapshots', ], }, { diff --git a/static/img/inspect.png b/static/img/inspect.png new file mode 100644 index 00000000000..d32bc2a25a5 Binary files /dev/null and b/static/img/inspect.png differ diff --git a/static/img/snapshots1.png b/static/img/snapshots1.png new file mode 100644 index 00000000000..639cbfee331 Binary files /dev/null and b/static/img/snapshots1.png differ diff --git a/static/img/snapshots2.png b/static/img/snapshots2.png new file mode 100644 index 00000000000..dc44843bf3f Binary files /dev/null and b/static/img/snapshots2.png differ diff --git a/static/img/snapshots3.png b/static/img/snapshots3.png new file mode 100644 index 00000000000..8ec782bdba3 Binary files /dev/null and b/static/img/snapshots3.png differ diff --git a/static/img/snapshots4.png b/static/img/snapshots4.png new file mode 100644 index 00000000000..46bbde2de69 Binary files /dev/null and b/static/img/snapshots4.png differ diff --git a/static/img/snapshots5.png b/static/img/snapshots5.png new file mode 100644 index 00000000000..27de4d926b9 Binary files /dev/null and b/static/img/snapshots5.png differ diff --git a/static/img/snapshots6.png b/static/img/snapshots6.png new file mode 100644 index 00000000000..a4e70646f60 Binary files /dev/null and b/static/img/snapshots6.png differ