# Flow frontmatter API

Copy as Markdown[View as Markdown](/docs/api/flow-api.md)

***

## Overview[​](#overview "Direct link to Overview")

Flows are just markdown files, with this comes the use of Content, MDX components and also [front-matter](https://jekyllrb.com/docs/front-matter/).

Here is an example of of a basic flow.

/events/InventoryOutOfStock/index.mdx (example)

```
---
# id of the flow
id: "CancelSubscriptionFlow"

# Display name of the flow, rendered in EventCatalog
name: "User Cancels Subscription"

# version for your flow 
version: "0.0.1"

# Short summary of your event
summary: "Flow for when a user has cancelled a subscription"

# A list of steps for your flow
steps:
  
  # id of your step, required for linking between stages in your flow
  - id: "cancel_subscription_initiated"
    # rendered title of your step
    title: "Cancels Subscription"
    # Short summary of a step
    summary: "User cancels their subscription"
    # Defining an actor will render an actor node in the graph.
    actor:
      name: "User"
    # What happens next? Define the next step  
    next_step: 
      id: "cancel_subscription_request"
      label: "Initiate subscription cancellation"

  - id: "cancel_subscription_request"
    title: "Cancel Subscription"
    # This step is a message, include the message and version
    message:
      id: "CancelSubscription"
      version: "0.0.1"
    next_step: 
      id: "subscription_service"
      label: "Proceed to subscription service"

  - id: "stripe_integration"
    title: "Stripe"
    # This is an external system (e.g Stripe)
    externalSystem:
      name: "Stripe"
      summary: "3rd party payment system"
      url: "https://stripe.com/"
    next_step: 
      id: "subscription_service"
      label: "Return to subscription service"

  - id: "subscription_service"
    title: "Subscription Service"
    # This node is a service, include that.
    service:
      id: "SubscriptionService"
      version: "0.0.1"
    # Define multiple steps
    next_steps:
      - id: "stripe_integration"
        label: "Cancel subscription via Stripe"
      - id: "subscription_cancelled"
        label: "Successful cancellation"
      - id: "subscription_rejected"
        label: "Failed cancellation"

  - id: "subscription_cancelled"
    title: "Subscription has been Cancelled"
    message:
      id: "UserSubscriptionCancelled"
      version: "0.0.1"
    next_step:
      id: "notification_service"
      label: "Email customer"

  - id: "subscription_rejected"
    title: "Subscription cancellation has been rejected"

  - id: "notification_service"
    title: "Notifications Service"
    service:
      id: "NotificationService"
      version: "0.0.2"

---

This flow documents what happens when a User Cancels Subscription in our system. 

<NodeGraph />

<!-- Add any markdown you want, the workflow will also render in its own page /docs/flows/{Flow}/{version} -->
```

## Required fields[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `CancelSubscriptionFlow`

Unqiue id of the flow. EventCatalog uses this for references and slugs.

Example

```
---
  id: InventoryOutOfStock
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

Name of the flow this is used to display the name on the UI.

Example

```
---
  name: User Cancels Subscription
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the flow.

Example

```
---
  version: 0.0.1
---
```

### `steps`[​](#steps "Direct link to steps")

* Type: `Step[]`

List of steps for your flow.

Example

```
---
steps:
  - id: "cancel_subscription_initiated"
    title: "Cancels Subscription"
    summary: "User cancels their subscription"
    # Define a single step that happens next
    next_step: 
      id: "cancel_subscription_request"
      label: "Initiate subscription cancellation"
    # OR define a multiple next steps
    next_steps:
        - id: "stripe_integration"
          label: "Cancel subscription via Stripe"
        - id: "subscription_cancelled"
          label: "Successful cancellation"
        - id: "subscription_rejected"
          label: "Failed cancellation"
---
```

#### Actor Nodes[​](#actor-nodes "Direct link to Actor Nodes")

Flows allow you to create [Actor nodes](https://en.wikipedia.org/wiki/Event_storming). Actors represent A person who executes a command or flow.

Example

```
---
  steps:
    - id: "cancel_subscription_initiated"
      title: "Cancels Subscription"
      summary: "User cancels their subscription"
      # Defining an actor will render an actor node in the graph.
      actor:
        name: "User"
      next_step: 
        id: "cancel_subscription_request"
        label: "Initiate subscription cancellation"
---
```

#### External Services Nodes[​](#external-services-nodes "Direct link to External Services Nodes")

Flows allow you to create External Service. These services tend to be other external services you may interact with that are not part of your business domain. (e.g Stripe API)

Example

```
---
  steps:
    - id: "stripe_integration"
      title: "Stripe"
      # This is an external system (e.g Stripe)
      externalSystem:
        name: "Stripe"
        summary: "3rd party payment system"
        url: "https://stripe.com/"
      next_step: 
        id: "subscription_service"
        label: "Return to subscription service"
---
```

*[See example of Actor node in a workflow](https://demo.eventcatalog.dev/visualiser/flows/CancelSubscription/0.0.1).*

#### Message Nodes[​](#message-nodes "Direct link to Message Nodes")

Flows allow you to create [message nodes](/docs/messages.md). Messages link to your commands or events.

Example

```
---
  steps:
    - id: "cancel_subscription_request"
      title: "Cancel Subscription"
      # This step is a message, include the message and version
      message:
        id: "CancelSubscription"
        version: "0.0.1"
      next_step: 
        id: "subscription_service"
        label: "Proceed to subscription service"
---
```

*[See example of Message node in a workflow](https://demo.eventcatalog.dev/visualiser/flows/CancelSubscription/0.0.1).*

#### Service Nodes[​](#service-nodes "Direct link to Service Nodes")

Flows allow you to create [service nodes](/docs/services.md). Services link to your defined services in EventCatalog.

Example

```
---
  - id: "subscription_service"
      title: "Subscription Service"
      # This node is a service, include that.
      service:
        id: "SubscriptionService"
        version: "0.0.1"
      # Define multiple steps
      next_steps:
        - id: "stripe_integration"
          label: "Cancel subscription via Stripe"
        - id: "subscription_cancelled"
          label: "Successful cancellation"
        - id: "subscription_rejected"
          label: "Failed cancellation"
---
```

*[See example of Message node in a workflow](https://demo.eventcatalog.dev/visualiser/flows/CancelSubscription/0.0.1).*

#### Container Nodes[​](#container-nodes "Direct link to Container Nodes")

**Added in** `eventcatalog@3.36.3`

Flows allow you to create [container (data store) nodes](/docs/development/guides/data/introduction.md). Containers link to your defined data stores in EventCatalog. The container's sidebar will automatically show a "Flows" section linking back to any flow that references it.

Example

```
---
  steps:
    - id: "orders_db"
      title: "Orders DB"
      container:
        id: "orders-db"
        version: "1.0.0"
      next_step:
        id: "next_step"
        label: "Persist order records"
---
```

#### Data Product Nodes[​](#data-product-nodes "Direct link to Data Product Nodes")

**Added in** `eventcatalog@3.36.3`

Flows allow you to create [data product nodes](/docs/development/guides/data-products/introduction.md). Data products link to your defined data products in EventCatalog. The data product's sidebar will automatically show a "Flows" section linking back to any flow that references it.

Example

```
---
  steps:
    - id: "order_analytics"
      title: "Order Analytics"
      dataProduct:
        id: "order-analytics"
        version: "1.0.0"
      next_step:
        id: "next_step"
        label: "Prepare fulfillment KPIs"
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

Short summary of your flow, shown on flow summary pages.

Example

```
---
  summary: |
    Flow that explains how a user unsubscribes to our system
---
```

### `badges`[​](#badges "Direct link to badges")

**Added in** `eventcatalog@3.39.4`

An array of badges that get rendered on the page.

Example

```
---
  badges:
    - content: My badge
      backgroundColor: green
      textColor: green
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---
```

#### Use named colors[​](#use-named-colors "Direct link to Use named colors")

Set `backgroundColor` or `textColor` to a named palette token for automatic light/dark mode adaptation.

Supported names: `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.

Named color example

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

#### Use any CSS color[​](#use-any-css-color "Direct link to Use any CSS color")

You can also pass any valid CSS color value directly: hex (`#ff0000`), `rgb()`, `hsl()`, `oklch()`, or a CSS variable (`var(--my-color)`).

CSS color example

```
---
  badges:
    - content: Custom
      backgroundColor: "#6366f1"
      textColor: "#ffffff"
---
```

#### Link to external URLs[​](#link-to-external-urls "Direct link to Link to external URLs")

**Added in** `eventcatalog@3.39.6`

Add a `url` to a badge to make it render as a clickable link with an external-link icon. When `url` is omitted, the badge renders as a plain label.

Link badge example

```
---
  badges:
    - content: View Runbook
      url: https://runbooks.example.com/my-flow
      backgroundColor: blue
      textColor: white
---
```

### `editUrl`[​](#editUrl "Direct link to editUrl")

**Added in** `eventcatalog@2.49.4`

Override the default edit url for the page. This is used to navigate the user to the edit page for the page (e.g GitHub, GitLab url).

Example

```
---
  editUrl: https://github.com/event-catalog/eventcatalog/edit/main/flows/CancelSubscription/index.mdx
---
```

### `detailsPanel`[​](#detailsPanel "Direct link to detailsPanel")

**Added in** `eventcatalog@2.53.0`

Override the default details panel for the page. You can use this show/hide areas of the details panel.

![Details panel](/assets/images/domain-details-panel-71f92ae7e5cc2ed29bb9254c2bd3dcb4.png)

Example

```
---
  detailsPanel:
    owners:
      visible: false
---
```

Options:

| Property    | Type     | Required | Description                                                           |
| ----------- | -------- | -------- | --------------------------------------------------------------------- |
| `owners`    | `object` | No       | An object with a `visible` property to show/hide the owners section   |
| `versions`  | `object` | No       | An object with a `visible` property to show/hide the versions section |
| `changelog` | `object` | No       | An object with a `visible` property to show/hide the changelog button |

### `attachments`[​](#attachments "Direct link to attachments")

**Added in** `eventcatalog@2.57.2`

An array of attachments for this resource type.

Example

```
---
  attachments:
    - url: https://example.com/adr/001
      title: ADR-001 - Use Kafka for asynchronous messaging
      description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
      type: 'architecture-decisions'
      icon: FileTextIcon
    - https://example.com/adr/002
---
```

Options:

The attachments can be a url (string) or an object with additional properties.

Object properties:

| Property      | Type     | Required | Description                                                                                          |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `url`         | `string` | Yes      | The url of the attachment                                                                            |
| `title`       | `string` | optional | The title of the attachment                                                                          |
| `description` | `string` | optional | The description of the attachment                                                                    |
| `type`        | `string` | optional | The type of the attachment, this will be used to group attachments together in the UI                |
| `icon`        | `string` | optional | The icon of the attachment, you can pick from the [lucide icons](https://lucide.dev/icons/) library. |