Flows reference

View as Markdown

---

This page lists the fields, paths, and routes supported by flows.

Paths

Flows can be created in any flows folder:

/flows/{Flow Name}/index.mdx
/domains/{Domain Name}/flows/{Flow Name}/index.mdx
/services/{Service Name}/flows/{Flow Name}/index.mdx

Versioned flows use:

/flows/{Flow Name}/versioned/{version}/index.mdx

Routes

Route	Description
/docs/flows/{flow-id}/{version}	Flow documentation page.
/docs/flows/{flow-id}/{version}/resources	Resources the flow's steps use (5.0.0+). Only built when the flow has at least one resource.
/visualiser/flows/{flow-id}/{version}	Flow diagram.

The flow diagram accepts these query parameters (5.0.0+). See Explore flows.

Parameter	Values	Description
group	domain, system, team, domain-system	Group the steps.
groupStyle	boxes, lanes	Draw the groups as boxes or lanes. Defaults to boxes.

Required fields

id

• Type: string

Unique id of the flow. EventCatalog uses this for URLs and resource references.

Example

---
id: checkout-flow
---

name

• Type: string

Display name of the flow.

Example

---
name: Checkout Flow
---

version

• Type: string

Version of the flow documentation.

Example

---
version: 1.0.0
---

Optional fields

summary

• Type: string

Short description of the flow.

Example

---
summary: Describes the steps from checkout start to order confirmation.
---

owners

• Type: array

An array of team or user ids that own the flow.

Example

---
owners:
  - checkout-platform
---

steps

• Type: array

Ordered steps in the flow.

Example

---
steps:
  - id: submit-order
    title: Submit order
    message:
      id: SubmitOrder
    next_step: authorize-payment
---

badges

• Type: array

Badges rendered on the flow page.

Example

---
badges:
  - content: Critical path
    backgroundColor: red
    textColor: red
---

repository

• Type: object

Repository metadata for the flow.

Example

---
repository:
  language: TypeScript
  url: https://github.com/acme/checkout
---

diagrams

• Type: array

Diagrams associated with the flow.

Example

---
diagrams:
  - id: checkout-sequence
    version: 1.0.0
---

attachments

• Type: array

External links or supporting documents attached to the flow.

Example

---
attachments:
  - title: Checkout runbook
    url: https://runbooks.example.com/checkout
    type: runbook
---

Step fields

Each flow step supports:

Field	Type	Description
id	string or number	Unique step id. Required.
title	string	Optional step title. Defaults to the name of what the step references (or the actor, external system or custom node's name, or the step's id).
summary	string	Optional step summary.
type	string	Accepted but ignored.
message	object	Message referenced by this step.
agent	object	Agent referenced by this step.
service	object	Service referenced by this step.
channel	object	Channel referenced by this step (5.0.0+).
flow	object	Nested flow referenced by this step.
container	object	Data store referenced by this step.
dataProduct	object	Data product referenced by this step.
actor	object	Inline actor for this step.
custom	object	Custom node for this step.
externalSystem	object	External system for this step.
next_step	string, number or object	Next step id, or { id, label }.
next_steps	array	Multiple next steps, each an id or { id, label }.
x-*	any	Your own step metadata.

Resource references (message, agent, service, channel, flow, container, dataProduct) take an id and an optional version (defaults to latest).

From 5.0.0, the build fails when a step:

• has a property that isn't listed above and doesn't start with x-
• uses more than one node type (for example message and service)
• uses both next_step and next_steps

A next_step to a step that isn't in the flow, or a reference to a resource that isn't in the catalog, logs a warning. See Mistakes in flow steps.

External services nodes

Use externalSystem when a flow step points at a third-party system.

---
steps:
  - id: payment-provider
    title: Payment provider
    externalSystem:
      name: Stripe
      summary: External payment processor.
    next_step: complete
---

Actor nodes

Use actor when a flow step represents a person, role, or external participant.

---
steps:
  - id: customer
    title: Customer starts checkout
    actor:
      name: Customer
    next_step: submit-order
---

Custom properties

You can add organization-specific metadata to this resource using frontmatter fields prefixed with x-. Learn how to define, render, and reference them in Custom properties on resources.