on GitHub" data-tooltip-id=":Rblcldtb:">v2.6·
In this chapter, you’ll learn about workflows and how to define and execute them.
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:
You implement all custom flows within workflows, then execute them from API routes, subscribers, and scheduled jobs.
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:
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
:
This adds another step whose function accepts as a parameter an object with a name
property.
Next, add the following to the same file to create the workflow using the createWorkflow
function:
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.
You can execute a workflow from different customizations:
To execute the workflow, invoke it passing the Medusa container as a parameter. Then, use its run
method:
To test out your workflow, start your Medusa application:
Then, if you added the API route above, send a GET
request to /workflow
:
You’ll receive the following response:
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:
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.