Flows

What are Flows?

Your systems architecture doesn't live in a static world, without interactions and data flows, so neither should your diagrams have to. With IcePanel Flows, you can show and explain the sequence of messages that run through your systems by each use case and focus on the objects and connections used. Flows can be adapted to show a range of interactions, from business use cases (how does our e-commerce system support a purchase?) to technical processes in your system (how do we authenticate users?).

This step-by-step approach will show you how to create and present different flows over the same diagrams seamlessly.

Flow step types

There are 8 step types:

🟢 Introduction

The Introduction step shows all steps in the current flow before showing each step at a time.

You can add details to explain what the flow is about as a way to set the scene before moving into each individual step.

➡️ Message

The Message step shows a message between 2 objects using an existing connection in the diagram.

🔄 Process

The Process steps show when a single model object does something.

Use the Process flow step for:

• Technical process you don't need the details for such as when an external object processes something for you and just returns the result such as "Process fraud check"

• Business processes such as "Ensure the new user is successfully onboarded"

• Actor actions that happen outside of your solution, such as "Send physical mail" or "Contact Brian from accounting".

◆ Alternate paths

The Alternate paths step allows you to split a flow and show different paths depending on a decision. This is to show OR decisions, when A or B or C ... are true compared to the others.

This is useful to show True / False decisions

It's also useful to show multiple options, such as:

• Authentication methods

• Payment methods

• Web app vs Android app vs Apple app

• etc.

🛣️ Parallel paths

The Parallel paths step allows you to show multiple steps happening in parallel or synchronously. This is to show AND decisions, when A and B and C ... are true alongside the others.

This is useful to show:

• Events/message broker with Producers with many consumers.

• Sending notifications to multiple systems

• Any asynchronous process

↱ Go to another flow

The Go to another flow step allows you to link multiple flows together. Use this to send people to another flow in the same or another diagram.

This is helpful to have high-level flows that have more detail lower down to tell a full story across multiple C4 model levels.

When you go to another flow, you get the option to return back to that step during or at the end of the other flow.

ℹ️ Information

The Information steps allow you to show important information that is not tied to any object or connection. Use this to add details to a flow that don't tie into anything in the diagram.

🏁 Conclusion

The Conclusion step is to show the flow has ended and shows all steps in the flow. It allows you to add some closing context to the end of the flow.

Creating a Flow

To create a new flow in a diagram:

1. Click on flow dropdown at the top left of the screen

2. Click New flow

3. Edit the flow name by clicking on the pencil icon in the list view

Adding steps to a Flow

To add steps to a flow:

1. Make sure you're in edit mode (The play button will be visible, CMD/CTRL + E)

2. Click the + Step button in your flow

3. The default step is a Message type between 2 objects. Click the Message button to change this.

4. Select the object you want to start the step from

5. Select the object that’s connected to your first selected object (the list will only show connected objects to the one you selected in step 2)

6. If there is only 1 connection between those objects, it will be auto selected. If you more than 1, select the connection you want to use for that step (the list will only show connections between those 2 objects in the current diagram)

7. Add a title to describe what happens in that step. Your title will be added with the step number to the current diagram, highlighting when that step is in focus. (optional)

8. Optional - You can also add more details for this step too - good for longer pieces of text of technical details.

Intelligent flow selection

Select an object or connection before adding a step to automatically fill the details of a step.

To do this:

1. Make sure you're in edit mode (The play button will be visible, CMD/CTRL + E)

2. Select a connection for a Message step type will be added with the objects, connection and title auto-filled.

3. Select the sender object and SHIFT select the receiever object for a Message step type will be added with the objects, connection and title auto-filled. This works in either direction of a conection.

4. Select an object for a Process step type will be added with the objects, connection and title auto-filled.

Reordering steps

You can reorder by dragging the grip icon by the number of the step card.

1. Make sure you're in the edit mode (The play button will be visible, CMD/CTRL + E)

2. Click and drag the grip handle to the left of a step card to the desired location.

3. A blue line will appear where the step will be placed when you let go.

To place in a path, drop on the path itself. The path will turn grey, indicating you're hovering on the right place.

Duplicating a step

To duplicate a step:

1. Make sure you're in the edit mode (The play button will be visible, CMD/CTRL + E)

2. Hover on the step you want to duplicate

3. Click the … menu item on the top right of the step

4. Click Duplicate step

Deleting steps

To delete a step:

1. Make sure you're in the edit mode (The play button will be visible)

2. Hover on the step you want to delete

3. Click the … menu item on the top right of the step

4. Click Delete step

Adding paths to a Flow

Paths allow you to communicate more complex logical steps in your flow. There are 3 types of paths in IcePanel — Alternate paths, Parallel paths, and Go to another flow.

Alternate paths

Alternate paths show steps based on a choice or scenario. For example, you may want to show different paths for a success or failure scenario. Think of these as OR scenarios.

To add an Alternate path:

1. Make sure you're in the edit mode (The play button will be visible, CMD/CTRL + E)

2. Click the + Step button

3. Change the step type to Alternate path

4. Add a first step by clicking on the + Step in path button nested in the path

5. To add more steps to the path, select a step before and click on the + Step in path button under that step.

6. You can edit the path name by first clicking on the dropdown menu at the top of the path, then on the pencil icon of the path

To add another path in the alternate path:

1. Click on the dropdown menu at the top of the path

2. Click on the Add path button

The group of paths also has a title, which you can use to explain the decision being made and use each path names to explain the choices.

Parallel paths

Parallel paths are useful for showing asynchronous steps, for example, a messaging queue or any scenario with parallelization. Think of these as AND scenarios.

To create a Parallel path:

1. Make sure you're in the edit mode (The play button will be visible, CMD/CTRL + E)

2. Click the + Step button

3. Change the step type to Parallel path

4. Add a first step by clicking on the + Step in path button nested in the path

5. To add more steps to the path, select a step before and click on the + Step in path button under that step.

6. You can edit the path name by first clicking on the dropdown menu at the top of the path, then on the pencil icon of the path.

To add another path in the parallel path:

1. Click on the dropdown menu at the top of the path

2. Click on the Add path button

The group of paths also has a title, which you can use to explain the decision being made and use each path names to explain the choices.

Go to flow

Once you have many flows across different diagrams in your domain, you can connect them to communicate even richer stories.

To add a Go to another flow step:

1. Click the + Step button under the active step

2. Change step type to Go to another flow

3. Click on the Select flow dropdown

4. Select the flow you want to link

Duplicating a path

1. Click on the paths dropdown

2. Click on the … menu item on the right of the path you want to duplicate

3. Click on the Duplicate path button

Deleting paths

To delete a single path:

1. Click on the paths dropdown

2. Click on the … menu item on the right of the path you want to duplicate

To delete all paths:

1. Click on the … menu at the top of the paths

2. Click the Delete button

Presenting flows

Presenting flows is a powerful way to focus attention on the topic you want to discuss in your System design. IcePanel allows you to navigate chronologically or non-linearly across your flow, depending on what you want to communicate.

There are a few ways to go through a flow:

• Press play to present the flow (we recommend hiding details until they're needed)

• Use the Back and Next buttons at the top of the Flow editor

• Use the ⬅️ or ⬆️ (back) and ➡️ or ⬇️ (next) arrow keys on the keyboard

• Click each step in the Flow steps dropdown

• Click the step on a connection directly in the diagram

Flows with paths

Here are a few things to keep in mind when you present flows with paths:

• For Alternate Paths, the flow will highlight the first path created by default in the diagram. Use the ⇥ button on the right of the path area to navigate through the different paths

• For Parallel Paths, the first step of each path will be highlighted by default. For example, if you have 3 different paths in a parallel path, the first step of each will be highlighted when you navigate to the path. Afterwards, the flow will navigate through the first path created by default

• For Go to flow paths, the Next button will change to Go to flow and navigate to that flow by default. You can skip this by clicking the Skip flow button at the bottom of the step.

You can rearrange path orders by clicking on the dropdown menu in the path and using the draggable area on the left of each path.

Visual options

Flows also come with a few additional visual customizations when presenting:

1. First, click on the … menu item on the right of the Flow editor

2. To show all connection names in the diagram, click the checkbox next to that option (this is turned off by default)

3. To show all steps in the flow, click the checkmark next to that option (by default, flows will only show the descriptions of the previous and next steps). If this is turned on, step titles for each step will appear in your diagram

Duplicate a Flow

To duplicate a flow:

1. Open the flow you want to duplicate or the list of flows in the dropdown

2. Click on the … menu item on the right of the Flow editor

3. Click on the Duplicate flow button

Deleting a Flow

To delete a flow:

1. Open the flow you want to delete or the list of flows in the dropdown

2. Click on the … menu item on the right of the Flow editor

3. Click on the Delete flow button

4. Click on the Delete button to confirm

Exporting a Flow

IcePanel supports exports in a few formats if you plan on sharing images/PDFs of your diagrams or want to visualize them as sequence diagrams.

Copy flow as text

This will copy your steps chronologically with object names, step types, step title, connection names, and paths. This can be useful to append to an image or PDF of your diagram.

To copy a flow as text:

1. Open the flow you want to copy or the list of flows

2. Click on the … menu item on the right of the flow editor

3. Click on the Copy flow as text button

Example output:

Introduction: Notes about this flow
- Step 1: User: This happens first
- Step 2: User -> API service: Thing happens via Request PNG or PDF export
- Step 3: API service -> Export topic: Then this happens via Publish export request

Copy flow as code

To export your flow as code to create a sequence diagram:

1. Open the flow you want to copy or the list of flows

2. Click on the … menu item on the right of the Flow editor

3. Click on the Copy flow as code button

4. Paste the code in a UML tool like PlantUML or WebSequenceDiagrams