# 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).*

## 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")

An array of badges that get rendered on the page.

Example

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

### `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. |