Workflows

In this chapter, you’ll learn about workflows and how to define and execute them.

What is a Workflow?#

In digital commerce you typically have many systems involved in your operations. For example, you may have an ERP system that holds product master data and accounting reports, a CMS system for content, a CRM system for managing customer campaigns, a payment service to process credit cards, and so on. Sometimes you may even have custom built applications that need to participate in the commerce stack. One of the biggest challenges when operating a stack like this is ensuring consistency in the data spread across systems.

Medusa has a built-in durable execution engine to help complete tasks that span multiple systems. You orchestrate your operations across systems in Medusa instead of having to manage it yourself. Other commerce platforms don't have this capability, which makes them a bottleneck to building customizations and iterating quickly.

A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow similar to how you create a JavaScript function.

However, unlike regular functions, workflows:

• Create an internal representation of your steps, allowing you to track them and their progress.
• Support defining roll-back logic for each step, so that you can handle errors gracefully and your data remain consistent across systems.
• Perform long actions asynchronously, giving you control over when a step starts and finishes.

You implement all custom flows within workflows, then execute them from API routes, subscribers, and scheduled jobs.

How to Create and Execute a Workflow?#

1. Create the Steps#

A workflow is made of a series of steps. A step is created using createStep from the Workflows SDK.

Create the file src/workflows/hello-world.ts with the following content:

src/workflows/hello-world.ts
1import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"2
3const step1 = createStep(4  "step-1", 5  async () => {6    return new StepResponse(`Hello from step one!`)7  }8)

The createStep function accepts the step's unique name as a first parameter, and the step's function as a second parameter.

Steps must return an instance of StepResponse, whose parameter is the data to return to the workflow executing the step.

Steps can accept input parameters. For example, add the following to src/workflows/hello-world.ts:

src/workflows/hello-world.ts
1type WorkflowInput = {2  name: string3}4
5const step2 = createStep(6  "step-2", 7  async ({ name }: WorkflowInput) => {8    return new StepResponse(`Hello ${name} from step two!`)9  }10)

This adds another step whose function accepts as a parameter an object with a name property.

2. Create a Workflow#

Next, add the following to the same file to create the workflow using the createWorkflow function:

src/workflows/hello-world.ts
1import {2  // other imports...3  createWorkflow,4  WorkflowResponse,5} from "@medusajs/framework/workflows-sdk"6
7// ...8
9const myWorkflow = createWorkflow(10  "hello-world",11  function (input: WorkflowInput) {12    const str1 = step1()13    // to pass input14    const str2 = step2(input)15
16    return new WorkflowResponse({17      message: str2,18    })19  }20)21
22export default myWorkflow

The createWorkflow function accepts the workflow's unique name as a first parameter, and the workflow's function as a second parameter. The workflow can accept input which is passed as a parameter to the function.

The workflow must return an instance of WorkflowResponse, whose parameter is returned to workflow executors.

3. Execute the Workflow#

You can execute a workflow from different customizations:

• Execute in an API route to expose the workflow's functionalities to clients.
• Execute in a subscriber to use the workflow's functionalities when a commerce operation is performed.
• Execute in a scheduled job to run the workflow's functionalities automatically at a specified repeated interval.

To execute the workflow, invoke it passing the Medusa container as a parameter. Then, use its run method:

4. Test Workflow#

To test out your workflow, start your Medusa application:

npm
yarn
pnpm

Then, if you added the API route above, send a GET request to /workflow:

Code
curl http://localhost:9000/workflow

You’ll receive the following response:

Example Response
1{2  "message": "Hello John from step two!"3}

Access Medusa Container in Workflow Steps#

A step receives an object as a second parameter with configurations and context-related properties. One of these properties is the container property, which is the Medusa container to allow you to resolve framework and commerce tools in your application.

For example, consider you want to implement a workflow that returns the total products in your application. Create the file src/workflows/product-count.ts with the following content:

src/workflows/product-count.ts
Show Imports
6} from "@medusajs/framework/workflows-sdk"7
8const getProductCountStep = createStep(9  "get-product-count", 10  async (_, { container }) => {11    const productModuleService = container.resolve("product")12
13    const [, count] = await productModuleService.listAndCountProducts()14
15    return new StepResponse(count)16  }17)18
19const productCountWorkflow = createWorkflow(20  "product-count",21  function () {22    const count = getProductCountStep()23
24    return new WorkflowResponse({25      count,26    })27  }28)29
30export default productCountWorkflow

In getProductCountStep, you use the container to resolve the Product Module's main service. Then, you use its listAndCountProducts method to retrieve the total count of products and return it in the step's response. You then execute this step in the productCountWorkflow.

You can now execute this workflow in a custom API route, scheduled job, or subscriber to get the total count of products.