From 2c1ba3eecb23454c057a57a9fc9a5d824acfa180 Mon Sep 17 00:00:00 2001
From: Joe Clark <jclark@openfn.org>
Date: Thu, 27 Jun 2024 12:18:10 +0100
Subject: [PATCH] updated edge condition docs

---
 docs/build/paths.md | 56 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 16 deletions(-)

diff --git a/docs/build/paths.md b/docs/build/paths.md
index b76638a9359..45307bdabfa 100644
--- a/docs/build/paths.md
+++ b/docs/build/paths.md
@@ -9,34 +9,58 @@ and configuration tips.
 
 ## Path Conditions
 
-There are 4 types of Path Conditions that define whether the Workflow will
+There are four types of Path Conditions that define whether the Workflow will
 proceed to the next Step when executed:
 
-1. Always (the next Step will always run after the execution of the prior Step
-   is completed)
-2. On Success (the next Step will run only if the execution of the prior Step
-   _succeeded_)
-3. On Failure (the next Step will run only if the execution of the prior Step
-   _failed_)
-4. Matches a JavaScript Expression (the next Step will only run if the condition
-   or custom expression evaluates to be true)
+1. **Always**: the next Step will always run after the execution of the prior
+   Step is completed
+2. **On Success**: the next Step will run only if the execution of the prior
+   Step _succeeded_
+3. **On Failure**: the next Step will run only if the execution of the prior
+   Step _failed_
+4. **Matches a JavaScript Expression**: the next Step will only run if an
+   expression evaluates to be true
 
 ![Path Conditions](/img/path_conditions.png)
 
 ## Writing JavaScript Expressions for Custom Path Conditions
 
-Write your own JavaScript expression if you want to define a **custom
-condition** that evaluates the initial state of the step.
+Create a **custom condition** with a JavaScript expression. This evaluates
+against the state produced by the previous Step.
 
-The workflow will only continue to the next step if if the JavaScript expression
-evaluates to be true.
+```
+state.data.form['@name'] === "Register New Patient"
+```
+
+This is a regular Javsacript expression with `state` in scope. If the expression
+evaluates to true (or anything _truthy_), the Path will be followed and the next
+Step will be executed.
 
 ![Custom Conditions](/img/path_js_expression.png)
 
-## Disable Paths to deactivate
+Examples of valid conditions include:
+
+- Run if there are no errors: `!state.errors`
+- Run if some value exists on state: `state.has_valid_email_address`
+- Run if a data array contains any items: `state.data.length > 0`
+- Run if data includes one item which matches criteria:
+  `state.data.includes(item => item.age > 18)`
+- Run if the last Step received a HTTP error: `state.response.statusCode >= 400`
+
+In a custom expression you **cannot** do any of the following:
+
+- Use adaptor functions
+- Use Lazy State references (`$`).
+- Use control statements like `if`, `while`, `for`, etc
+
+## Disabling Paths
+
+Disabling a path will prevent any of the downstream Steps from running,
+regardless of the condition or state.
+
+This can be a useful way of temporarily deactivating part of your workflow.
 
-To "deactivate" part of your Workflow and the Steps that follow a specific Path
-sequence:
+To disable a path:
 
 1. Click on the `Path` you want to deactive
 2. Select the `Disable this path` checkbox