Flows

Flows group related Steps together so you can see them as connected workflows in Workbench. Add flows to your Step config - it's an array of flow names.

How It Works

Add flows to any Step config. Each string is a flow name.

export const config: ApiRouteConfig = {
  name: 'CreateResource',
  type: 'api',
  path: '/resources',
  method: 'POST',
  flows: ['resource-management']
}

Example

Two Steps working together in one flow.

API and Event Steps connected in a flow

API Step - Create resource:

steps/create-resource.step.ts

import { ApiRouteConfig, Handlers } from 'motia'
 
export const config: ApiRouteConfig = {
  name: 'CreateResource',
  type: 'api',
  path: '/resources',
  method: 'POST',
  flows: ['resource-management'],
  emits: ['send-email']
}
 
export const handler: Handlers['CreateResource'] = async (req, { emit, logger }) => {
  logger.info('Creating resource', { title: req.body.title })
  
  await emit({ 
    topic: 'send-email', 
    data: { email: req.body.email } 
  })
  
  return { status: 201, body: { id: '123' } }
}

Event Step - Send email:

steps/send-email.step.ts

import { EventConfig, Handlers } from 'motia'
 
export const config: EventConfig = {
  name: 'SendEmail',
  type: 'event',
  subscribes: ['send-email'],
  flows: ['resource-management']
}
 
export const handler: Handlers['SendEmail'] = async (input, { logger }) => {
  logger.info('Sending email', { email: input.email })
  // Email sending logic here
}

👉 Both Steps have flows: ['resource-management']. In Workbench, they appear connected.

Multiple Flows

A Step can belong to multiple flows.

export const config: EventConfig = {
  name: 'SendEmail',
  type: 'event',
  subscribes: ['send-email'],
  flows: ['resource-management', 'user-onboarding']
}

👉 This Step appears in both flows in Workbench.

Steps Without Flows

Steps work fine without flows.

export const config: ApiRouteConfig = {
  name: 'HealthCheck',
  type: 'api',
  path: '/health',
  method: 'GET'
}

Flows in Workbench

Workbench has a dropdown to filter by flow. Select a flow to see only the Steps that belong to it.

Flow dropdown in Workbench

Virtual Connections

Use virtualEmits and virtualSubscribes for visualization without actual events:

export const config: ApiRouteConfig = {
  name: 'CreateResource',
  type: 'api',
  path: '/resources',
  method: 'POST',
  virtualEmits: ['approval.required'],
  flows: ['resource-management']
}

Virtual connections show as gray/dashed lines in Workbench. Real connections (from emits and subscribes) show as dark solid lines.

Virtual connections with labels in Workbench

Labels

Add labels to connections in Workbench:

export const config: ApiRouteConfig = {
  name: 'SendEmail',
  type: 'api',
  path: '/send',
  method: 'POST',
  virtualEmits: [
    { topic: 'email-sent', label: 'Email delivered' },
    { topic: 'email-failed', label: 'Failed to send', conditional: true },
  ],
  flows: ['notifications']
}

NOOP Steps

NOOP Steps don't run code. They're for visualization only:

import { NoopConfig } from 'motia'
 
export const config: NoopConfig = {
  type: 'noop',
  name: 'ApprovalGate',
  virtualEmits: ['approved'],
  virtualSubscribes: ['approval.required'],
  flows: ['resource-management']
}
 
// No handler needed

👉 Learn about customizing how flows look →

Need help? See our Community Resources for questions, examples, and discussions.

On this page