Skip to main content

Creating flows

Added in eventcatalog@2.5.0

Adding a flow to your Catalog is a great way for you to document your workflows within your architecture.

What do flows look like in EventCatalog?​

Example

See a flow example.

Adding a new flow​

To add a new flow create a new folder (/flows). Create a subfolder with your flow name.

  • /flows/{Flow Name}/index.mdx
    • (example /flows/ProcessingPayments/index.mdx)

The index.mdx contents are split into two sections, frontmatter and the markdown content.

Here is an example of what a flow file may look like.

/flows/CancelSubscription/index.mdx (example)
---
id: "CancelSubscription"
name: "User Cancels Subscription"
version: "0.0.1"
summary: "Flow for when a user has cancelled a subscription"
steps:
  - id: "cancel_subscription_initiated"
    title: "Cancels Subscription"
    summary: "User cancels their subscription"
    # define the actor for, in this case it's a user.
    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} -->

That's it!

Once you add your new flows to EventCatalog, it will now show in the docs, visualizer and discoverability table.

Adding content​

With flows you can write any Markdown you want and it will render on your page. Every flow gets its own page.

Within your markdown content you can use components to add interactive components to your page.

Adding child flows / reusable flows​

Added in eventcatalog@2.34.2

You can reference a flow from another flow. This lets you reuse flows in your flow diagrams, useful if you have complex flows that reuse information from another flow.

To reference a flow from another flow, use the flow node type.

steps:
  - id: "step-1"
    title: "Example Step of a Event"
    flow:
      id: "order-flow"
      version: 0.0.1

This will render the order-flow within the described flow. Right clicking on the order-flow node will let you navigate to the referenced flow.

Tips for flow content​

It's entirely up to you what you want to add to your flows markdown content but here are a few things you might want to consider.

  • Context of the flow. What is it? Why does it exist?
  • Examples of how to trigger the flow?
  • Any edit/contributing guidelines?