From 823552ecd92ce0271f16b412844f9c6f95171b24 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Wed, 13 Nov 2024 11:00:37 +0200
Subject: [PATCH] docs: document multiple steps usage in a workflow (#10053)

---
 .../workflows/multiple-step-usage/page.mdx    | 80 +++++++++++++++++++
 www/apps/book/generated/edit-dates.mjs        |  3 +-
 www/apps/book/sidebar.mjs                     |  5 ++
 3 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 www/apps/book/app/learn/advanced-development/workflows/multiple-step-usage/page.mdx

diff --git a/www/apps/book/app/learn/advanced-development/workflows/multiple-step-usage/page.mdx b/www/apps/book/app/learn/advanced-development/workflows/multiple-step-usage/page.mdx
new file mode 100644
index 0000000000..91db3d58c3
--- /dev/null
+++ b/www/apps/book/app/learn/advanced-development/workflows/multiple-step-usage/page.mdx
@@ -0,0 +1,80 @@
+export const metadata = {
+  title: `${pageNumber} Multiple Step Usage in Workflow`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to use a step multiple times in a workflow.
+
+## Problem Reusing a Step in a Workflow
+
+In some cases, you may need to use a step multiple times in the same workflow.
+
+The most common example is using the `useQueryGraphStep` multiple times in a workflow to retrieve multiple unrelated data, such as customers and products.
+
+Each workflow step must have a unique ID, which is the ID passed as a first parameter when creating the step:
+
+```ts
+const useQueryGraphStep = createStep(
+  "use-query-graph",
+  // ...
+)
+```
+
+This causes an error when you use the same step multiple times in a workflow, as it's registered in the workflow as two steps having the same ID:
+
+```ts
+const helloWorkflow = createWorkflow(
+  "hello",
+  () => {
+    const { data: products } = useQueryGraphStep({
+      entity: "product",
+      fields: ["id"]
+    })
+
+    // ERROR OCCURS HERE: A STEP HAS THE SAME ID AS ANOTHER IN THE WORKFLOW
+    const { data: customers } = useQueryGraphStep({
+      entity: "customer",
+      fields: ["id"]
+    })
+  }
+)
+```
+
+The next section explains how to fix this issue to use the same step multiple times in a workflow.
+
+---
+
+## How to Use a Step Multiple Times in a Workflow?
+
+When you execute a step in a workflow, you can chain a `config` method to it to change the step's config.
+
+Use the `config` method to change a step's ID for a single execution.
+
+So, this is the correct way to write the example above:
+
+export const highlights = [
+  ["13", "name", "Change the step's ID for this execution."]
+]
+
+```ts highlights={highlights}
+const helloWorkflow = createWorkflow(
+  "hello",
+  () => {
+    const { data: products } = useQueryGraphStep({
+      entity: "product",
+      fields: ["id"]
+    })
+
+    // ✓ No error occurs, the step has a different ID.
+    const { data: customers } = useQueryGraphStep({
+      entity: "customer",
+      fields: ["id"]
+    }).config({ name: "fetch-customers" })
+  }
+)
+```
+
+The `config` method accepts an object with a `name` property. Its value is a new ID of the step to use for this execution only.
+
+The first `useQueryGraphStep` usage has the ID `use-query-graph`, and the second `useQueryGraphStep` usage has the ID `fetch-customers`.
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index d8f050779a..27eef72c07 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -113,5 +113,6 @@ export const generatedEditDates = {
   "app/learn/advanced-development/data-models/infer-type/page.mdx": "2024-09-30T08:43:53.123Z",
   "app/learn/advanced-development/custom-cli-scripts/seed-data/page.mdx": "2024-10-03T11:11:07.181Z",
   "app/learn/basics/modules/page.mdx": "2024-10-16T08:49:39.997Z",
-  "app/learn/advanced-development/environment-variables/page.mdx": "2024-10-25T14:59:07.831Z"
+  "app/learn/advanced-development/environment-variables/page.mdx": "2024-10-25T14:59:07.831Z",
+  "app/learn/advanced-development/workflows/multiple-step-usage/page.mdx": "2024-11-12T11:11:49.191Z"
 }
\ No newline at end of file
diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs
index 757ff03283..c779323590 100644
--- a/www/apps/book/sidebar.mjs
+++ b/www/apps/book/sidebar.mjs
@@ -473,6 +473,11 @@ export const sidebar = numberSidebarItems(
               path: "/learn/advanced-development/workflows/execute-another-workflow",
               title: "Execute Another Workflow",
             },
+            {
+              type: "link",
+              path: "/learn/advanced-development/workflows/multiple-step-usage",
+              title: "Multiple Step Usage",
+            },
           ],
         },
         {