From 94bd778930e7d8aac7ba14221d6a0f4e940f005d Mon Sep 17 00:00:00 2001
From: Taylor Downs <downs.taylor@gmail.com>
Date: Fri, 23 Feb 2024 16:18:19 +0000
Subject: [PATCH] close #425

---
 docs/build/steps/state.md | 93 +++++++++++++++++++++++++++------------
 1 file changed, 64 insertions(+), 29 deletions(-)

diff --git a/docs/build/steps/state.md b/docs/build/steps/state.md
index 4db074ecd75..1796cf5d359 100644
--- a/docs/build/steps/state.md
+++ b/docs/build/steps/state.md
@@ -2,46 +2,81 @@
 title: Initial and final state
 ---
 
-Each Step has an initial state (which may contain an `Input`) and results in a
-final state that will include `Logs` and an `Output`. This article explains
-these concepts in greater detail.
+Each Step requires an input state and (in most cases) will produce an output
+state. This article explains these concepts in greater detail.
 
 ![Job State Overview](/img/state-javascript.png)
 
-## Initial state
+## Input & output state for runs
 
-Depending on whether you're running Workflows locally or on the app, the initial
-`state` for an individual Run might be generated differently. It could be
-generated manually (e.g., by creating a custom `Input` on the app or
-`state.json` file if working locally
-[in the CLI](/docs/build-for-developers/cli-intro.md)), or automatically when a
-webhook event is triggered as incoming data is received, or as a cron trigger is
-activated at the scheduled time.
+Depending on whether you're running Workflows locally or on the app, the input
+`state` for a Run can be generated differently. When creating a work order by
+hand, you must select or generate your input manually (e.g., by creating a
+custom `Input` on the app or `state.json` file if working locally
+[in the CLI](/docs/build-for-developers/cli-intro.md)). When a work order is
+automatically created via a webhook trigger or cron trigger, state will be
+created as described below.
 
-## Final state
+The final state of a Run is determined by what's returned from the last
+operation. Remember that job expressions are a series of `operations`—they each
+take `state` and return `state`, after creating any number of side effects. You
+can control what is returned at the end of all of these operations.
 
-The final state of a Run is determined by _you_. Remember that job expressions
-are a series of `operations`—they each take `state` and return `state`, after
-creating any number of side effects. You control what is outputted to hand off
-to the next Step and/or what is sent to the destination app.
+### Webhook triggered runs
 
-### Passing state to the next Step
+Initial state contains important parts of the inbound **http request**.
 
-See the below diagram for a visual description of how state might be passed between
-Steps in a Workflow.
+```js
+{
+  data: httpRequest.body,
+  request: { headers: httpRequest.headers },
+  configuration: credential.body
+}
+```
 
-![Passing State](/img/passing-state-steps.png)
+### Cron triggered runs
+
+Initiate state is either an empty object `{}` or the final state of the **last
+succesful run** for this workflow.
+
+```js
+{
+  ...finalStateOfLastSuccessfulRun,
+  configuration: credential.body
+}
+```
+
+## Input & output state for steps
+
+State is also passed between each step in a workflow. The output state of the
+previous step is used as the input state for the next step.
 
-### Final state after an error
+### On success
 
-If a Run fails, it will _not_ produce a final state. The run itself will have
-`log` information attached to it, along with its exit code, but there's not
-necessarily a clean final `state` or `Output` which can be serialized to `JSON`.
+When a job succeeds, its output state will be whatever is returned by the last
+operation.
 
-:::info
+```js
+{
+  data: "blah",
+  references: [1, 2, 3]
+}
+```
 
-If you have configured a Step that runs `on failure` of the prior Step, note
-that its initial state will be the initial state of the previous (failed) Run,
-plus a new `error` key that contains the stringified logs from the previous Run.
+### On failure
 
-:::
+When a step in a workflow fails, the error will be added to an `errors` object
+on state, keyed by the ID of the job that failed.
+
+```js
+{
+  data: "blah",
+  references: [1, 2, 3],
+  errors: { jobId: error }
+}
+```
+
+See the below diagram for a visual description of how state might be passed
+between Steps in a Workflow.
+
+![Passing State](/img/passing-state-steps.png)