Skip to main content

Flow frontmatter API

Overview​

Flows are just markdown files, with this comes the use of Content, MDX components and also 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​

id​

  • Type: CancelSubscriptionFlow

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

Example
---
  id: InventoryOutOfStock
---

name​

  • Type: string

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

Example
---
  name: User Cancels Subscription
---

version​

  • Type: string

Version of the flow.

Example
---
  version: 0.0.1
---

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​

Flows allow you to create Actor nodes. 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​

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.

Message Nodes​

Flows allow you to create message nodes. 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.

Service Nodes​

Flows allow you to create service nodes. 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.

Optional fields​

summary​

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

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

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​

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​

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

Example
---
  detailsPanel:
    owners:
      visible: false
---

Options:

PropertyTypeRequiredDescription
ownersobjectNoAn object with a visible property to show/hide the owners section
versionsobjectNoAn object with a visible property to show/hide the versions section
changelogobjectNoAn object with a visible property to show/hide the changelog button

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:

PropertyTypeRequiredDescription
urlstringYesThe url of the attachment
titlestringoptionalThe title of the attachment
descriptionstringoptionalThe description of the attachment
typestringoptionalThe type of the attachment, this will be used to group attachments together in the UI
iconstringoptionalThe icon of the attachment, you can pick from the lucide icons library.