Annotate flows

Annotate your flows to make them easy to understand at a glance. These annotations might benefit another flow builder in your organization, or they might benefit you if you haven't worked on the flow in a while.

To add an annotation to the flow canvas:

A screen capture of the DaVinci canvas with the CMD+Click context menu showing the Add Annotation option.
  1. CMD+Click (macOS) or CTRL+Click (Windows) a blank part of the canvas.
  2. Click Add Annotation.
  3. Click the annotation to enter the text and configure the appearance.

Use annotations to describe what happens in the main steps of the flow. Although there are rare occasions where a single node should have its own annotation, in most cases, you should use one annotation for each logical grouping of nodes.

A screen capture showing a flow with an annotation near each major portion of the flow.

Add meaningful node titles

On the Settings tab for each node, set the Node Title to a meaningful name that describes or identifies each node. This name appears in the flow canvas and, combined with the annotations, makes it easier to read the flow.

For example, consider the following flows. They are identical aside from node titles and annotations.

Recommended:
A screen capture showing an annotated flow with informative node titles.
Not recommended:
A screen capture showing an un-annotated flow with uninformative note titles.

Align nodes in straight lines with equal spacing

To make it easier to see the connections and overall structure, align your nodes in neat rows and columns. Avoid overlapping nodes and clustering them close together.

A screen capture showing two versions of a simple flow, with the first version neatly aligned and the second version sloppily aligned.

Use a single start node

Begin your flow with a single node that serves as a clear starting point. If you include loops in your flow, don't loop back to this start node. Instead, loop back to a later node.

Important: Do not begin the flow with a Teleport Start node. Routing to an initial Teleport Start node can cause flow timeout issues.

Host images outside of flows

Large images and assets should be hosted on a CDN and referenced from the flow, not packaged within the flow.

Use Teleport nodes for large flows

If you are creating a very large flow, you can use Teleport nodes to connect different sections of the flow. This makes the flow more readable by breaking it down into discrete sections. It can also let you reuse some sections of the flow rather than duplicating content.

Attention:

Configure the logical operator that immediately follows a destination Teleport node to All Triggers True. Use a different node following each destination Teleport node; don't create flow patterns where multiple destination Teleport nodes connect directly to the same node.

Consider flow limits

There are some limitations in flow creation, such as a maximum number of node exections and a maximum number of saved versions of each flow. Review these limitations before creating flows, as they may affect the way you create and update your flows. For more information, see Flow limits.

Consider flow complexity when designing and testing

The more complex the goal of a flow is, the more planning and testing is required to ensure that the flow works correctly. When planning a flow, bear in mind that some tasks and elements will increase the complexity and testing requirements:

  • Parallel branches that run simultaneously
  • Large amounts of data processing
  • Looping flows
  • Large flows
  • API normalization

Delete unused nodes

If you don't want an existing node to be part of the flow, delete it entirely instead of disconnecting or disabling it.

Delete unused flows

If you don't want to use a flow, delete it to make it easier to find relevant flows.