From c9586cd73a4913025daf705815cf04c843fc64e1 Mon Sep 17 00:00:00 2001
From: Joe Clark <joe@openfn.org>
Date: Fri, 17 Jan 2025 14:11:15 +0000
Subject: [PATCH] tweaks

---
 docs/build/workflows-api.md | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/docs/build/workflows-api.md b/docs/build/workflows-api.md
index a7405de62f0a..8934bc89331f 100644
--- a/docs/build/workflows-api.md
+++ b/docs/build/workflows-api.md
@@ -51,6 +51,7 @@ A Workflow has the following structure:
   "project_id": "79efba60-072a-4d4f-8d6c-22dfd3852176",
   "edges": [
     {
+      "id": "759fe475-ed23-4914-8a6d-155968bc0aa1"
       "condition_type": "always",
       "enabled": true,
       "source_job_id": null,
@@ -83,9 +84,11 @@ When creating a new Workflow, the server will generate UUIDs for the workflow
 and all steps and edges. You can use any id string you like in the creation of
 new nodes and edges - so long as id usage is consistent.
 
-When matching a PUT or PATCH request, new steps and edges must be given UUIDs.
+When matching a PUT or PATCH request, new steps and edges MUST be assigned
+UUIDs. If using the `http` adaptor, you can use `util.uuid()` for this (see the
+example below).
 
-You MUST ensure that all steps and triggers referenced by an edge are defined
+You MUST ensure that any steps and triggers referenced by an edge are defined
 within the same workflow.
 
 ## HTTP Adaptor Examples
@@ -96,7 +99,7 @@ Access Token (PAT) and `baseUrl` set to your OpenFn instance (ie,
 
 Create new Workflow:
 
-```
+```js
 post(`/api/projects/${$.projectId}/workflows`, {
   body: {
     name: 'My Workflow',
@@ -128,18 +131,20 @@ post(`/api/projects/${$.projectId}/workflows`, {
 ```
 
 The resulting workflow with updated UUIDs and metadata will be written to
-state.data.workflow
+`state.data.workflow`.
 
-Add a new step to an existing Workflow:
+Add a new step and edge to an existing Workflow:
 
-```
-fn((state) => {
-  const jobId = util.uuid()
+```js
+fn(state => {
+  const jobId = util.uuid();
   state.diff = {
     edges: [
       {
+        id: util.uuid(),
         source_job_id: 'c79ce46c-ab0f-4f5b-bf2d-fed52aef2a41',
         target_job_id: jobId,
+        condition_type: 'always',
       },
     ],
     jobs: [
@@ -149,12 +154,13 @@ fn((state) => {
         adaptor: '@openfn/language-common@latest',
       },
     ],
-  }
+  };
   return state;
-})
+});
 patch(`/api/projects/${$.projectId}/workflows/${$.workflowId}`, {
   body: $.diff,
   headers: { 'content-type': 'application/json' },
 });
-
 ```
+
+The resulting workflow will be written to `state.data.workflow`.