docs: document workflow retention (#11138)

2025-01-24 14:34:24 +02:00
parent c1ae373967
commit cdfde0dfac
4 changed files with 186 additions and 1 deletions
@@ -282,6 +282,12 @@ You use this step in another workflow that changes the status of an async step i

 To access the status and result of a long-running workflow execution, use the `subscribe` and `unsubscribe` methods of the Workflow Engine Module's main service.

+<Note title="Tip">
+
+To retrieve the workflow execution's details at a later point, you must enable [storing the workflow's executions](../store-executions/page.mdx).
+
+</Note>
+
 For example:

 export const highlights = [
@@ -0,0 +1,173 @@
+import { Prerequisites } from "docs-ui"
+
+export const metadata = {
+  title: `${pageNumber} Store Workflow Executions`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to store workflow executions in the database and access them later.
+
+## Workflow Execution Retention
+
+Medusa doesn't store your workflow's execution details by default. However, you can configure a workflow to keep its execution details stored in the database.
+
+This is useful for auditing and debugging purposes. When you store a workflow's execution, you can view details around its steps, their states and their output. You can also check whether the workflow or any of its steps failed.
+
+<Note title="Tip">
+
+You can view stored workflow executions from the Medusa Admin dashboard by going to Settings -> Workflows.
+
+</Note>
+
+---
+
+## How to Store Workflow's Executions?
+
+<Prerequisites
+  items={[
+    {
+      text: "Redis Workflow Engine must be installed and configured.",
+      link: "!resources!/architectural-modules/workflow-engine/redis"
+    }
+  ]}
+/>
+
+`createWorkflow` from the Workflows SDK can accept an object as a first parameter to set the workflow's configuration. To enable storing a workflow's executions:
+
+- Enable the `store` option. If your workflow is a [Long-Running Workflow](../long-running-workflow/page.mdx), this option is enabled by default.
+- Set the `retentionTime` option to the number of milliseconds that the workflow execution should be stored in the database.
+
+For example:
+
+export const highlights = [
+  ["15", "retentionTime", "The number of milliseconds that the workflow's executions should be stored in the database."],
+  ["16", "store", "Enable storing the workflow's executions in the database."],
+]
+
+```ts highlights={highlights}
+import { createStep, createWorkflow } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  {
+    name: "step-1"
+  },
+  async () => {
+    console.log("Hello from step 1")
+  }
+)
+
+export const helloWorkflow = createWorkflow(
+  {
+    name: "hello-workflow",
+    retentionTime: 99999,
+    store: true
+  },
+  () => {
+    step1()
+  }
+)
+```
+
+Whenever you execute the `helloWorkflow` now, its execution details will be stored in the database.
+
+---
+
+## Retrieve Workflow Executions
+
+<Note title="Tip">
+
+You can view stored workflow executions from the Medusa Admin dashboard by going to Settings -> Workflows.
+
+</Note>
+
+When you execute a workflow, the returned object has a `transaction` property containing the workflow execution's transaction details:
+
+```ts
+const { transaction } = await helloWorkflow(container).run()
+```
+
+To retrieve a workflow's execution details from the database, resolve the Workflow Engine Module from the container and use its `listWorkflowExecutions` method.
+
+For example, you can create a `GET` API Route at `src/workflows/[id]/route.ts` that retrieves a workflow execution for the specified transaction ID:
+
+export const retrieveHighlights = [
+  ["8", "transaction_id", "Get the transaction ID from a path parameter."],
+  ["10", "workflowEngineService", "Resolve the Workflow Engine Module from the container."],
+  ["14", "workflowExecution", "Retrieve the workflow execution for the specified transaction ID."],
+]
+
+```ts title="src/workflows/[id]/route.ts" highlights={retrieveHighlights}
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import { Modules } from "@medusajs/framework/utils";
+
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { transaction_id } = req.params
+  
+  const workflowEngineService = req.scope.resolve(
+    Modules.WORKFLOW_ENGINE
+  )
+
+  const [workflowExecution] = await workflowEngineService.listWorkflowExecutions({
+    transaction_id: transaction_id
+  })
+
+  res.json({
+    workflowExecution
+  })
+}
+```
+
+In the above example, you resolve the Workflow Engine Module from the container and use its `listWorkflowExecutions` method, passing the `transaction_id` as a filter to retrieve its workflow execution details.
+
+A workflow execution object will be similar to the following:
+
+```json
+{
+  "workflow_id": "hello-workflow",
+  "transaction_id": "01JJC2T6AVJCQ3N4BRD1EB88SP",
+  "id": "wf_exec_01JJC2T6B3P76JD35F12QTTA78",
+  "execution": {
+    "state": "done",
+    "steps": {},
+    "modelId": "hello-workflow",
+    "options": {},
+    "metadata": {},
+    "startedAt": 1737719880027,
+    "definition": {},
+    "timedOutAt": null,
+    "hasAsyncSteps": false,
+    "transactionId": "01JJC2T6AVJCQ3N4BRD1EB88SP",
+    "hasFailedSteps": false,
+    "hasSkippedSteps": false,
+    "hasWaitingSteps": false,
+    "hasRevertedSteps": false,
+    "hasSkippedOnFailureSteps": false
+  },
+  "context": {
+    "data": {},
+    "errors": []
+  },
+  "state": "done",
+  "created_at": "2025-01-24T09:58:00.036Z",
+  "updated_at": "2025-01-24T09:58:00.046Z",
+  "deleted_at": null
+}
+```
+
+### Example: Check if Stored Workflow Execution Failed
+
+To check if a stored workflow execution failed, you can check its `state` property:
+
+```ts
+if (workflowExecution.state === "failed") {
+  return res.status(500).json({
+    error: "Workflow failed"
+  })
+}
+```
+
+Other state values include `done`, `invoking`, and `compensating`.