How to Use the Workflow Engine Module

In this document, you’ll learn about the different methods in the Workflow Engine Module's service and how to use them.

Resolve Workflow Engine Module's Service#

In your workflow's step, you can resolve the Workflow Engine Module's service from the Medusa container:

Code
1import { Modules } from "@medusajs/framework/utils"2import { createStep } from "@medusajs/framework/workflows-sdk"3
4const step1 = createStep(5  "step-1",6  async ({}, { container }) => {7    const workflowEngineModuleService = container.resolve(8      Modules.WORKFLOW_ENGINE9    )10    11    // TODO use workflowEngineModuleService12  } 13)

This will resolve the service of the configured Workflow Engine Module, which is the In-Memory Workflow Engine Module by default.

You can then use the Workflow Engine Module's service's methods in the step. The rest of this guide details these methods.

retryStep#

This method retries a step that has temporary failed, such as a step that has autoRetry set to false or when the machine running the Medusa application shuts down. Learn more about it in the Retry Failed Steps guide.

Example#

Code
1// other imports...2import {3  TransactionHandlerType,4} from "@medusajs/framework/utils"5
6workflowEngine.retryStep({7  idempotencyKey: {8    action: TransactionHandlerType.INVOKE,9    transactionId,10    stepId: "step-1",11    workflowId: "hello-world",12  },13})

Parameters#

setStepSuccess#

This method sets an async step in a currently-executing long-running workflow as successful. The workflow will then continue to the next step.

Example#

Code
1// other imports...2import {3  TransactionHandlerType,4} from "@medusajs/framework/utils"5
6await workflowEngineModuleService.setStepSuccess({7  idempotencyKey: {8    action: TransactionHandlerType.INVOKE,9    transactionId,10    stepId: "step-2",11    workflowId: "hello-world",12  },13  stepResponse: new StepResponse("Done!"),14})

Parameters#

setStepFailure#

This method sets an async step in a currently-executing long-running workflow as failed. The workflow will then stop executing and the compensation functions of the workflow's steps will be executed.

Example#

Code
1// other imports...2import {3  TransactionHandlerType,4} from "@medusajs/framework/utils"5
6await workflowEngineModuleService.setStepFailure({7  idempotencyKey: {8    action: TransactionHandlerType.INVOKE,9    transactionId,10    stepId: "step-2",11    workflowId: "hello-world",12  },13  stepResponse: new StepResponse("Failed!"),14})

Parameters#

subscribe#

This method subscribes to a workflow's events. You can use this method to listen to a long-running workflow's events and retrieve its result once it's done executing.

Refer to the Long-Running Workflows documentation to learn more.

Example#

Code
1const { transaction } = await helloWorldWorkflow(container).run()2
3const subscriptionOptions = {4  workflowId: "hello-world",5  transactionId: transaction.transactionId,6  subscriberId: "hello-world-subscriber",7}8
9await workflowEngineModuleService.subscribe({10  ...subscriptionOptions,11  subscriber: async (data) => {12    if (data.eventType === "onFinish") {13      console.log("Finished execution", data.result)14      // unsubscribe15      await workflowEngineModuleService.unsubscribe({16        ...subscriptionOptions,17        subscriberOrId: subscriptionOptions.subscriberId,18      })19    } else if (data.eventType === "onStepFailure") {20      console.log("Workflow failed", data.step)21    }22  },23})

Parameters#

unsubscribe#

This method unsubscribes from a workflow's events. You can use this method to stop listening to a long-running workflow's events after you've received the result.

Example#

Code
1await workflowEngineModuleService.unsubscribe({2  workflowId: "hello-world",3  transactionId: "transaction-id",4  subscriberOrId: "hello-world-subscriber",5})

Parameters#