Actions

Annotations

Annotation components are for annotating templates. They are not executed as part of the stub execution, but can be used to provide additional context and information about the template.

# Overview

Annotations are visual notes and reference points that you can add to a template flow canvas. They help explain how a template is intended to work, group related areas of the canvas, and link to supporting resources.

Annotations are not actions and they are not executed when a stub runs. They exist to make the template easier to understand, maintain, and test.

# Uses

• Add context for future editors of a template
• Label sections of a large flow canvas
• Link to supporting documentation, examples, or external systems
• Keep notes close to the states and actions they describe

# Annotation Types

# URL

The url annotation links to an external resource from the canvas.

Use a URL annotation when the flow depends on, or is explained by, something outside Stubber. For example:

• API documentation
• A design document
• A customer portal
• A spreadsheet or shared document
• A reference page for an integration

URL annotations make it easy for someone working on the template to open the relevant external resource without searching through separate notes or documentation.

# Header

The header annotation creates a large header on the canvas.

Use a header annotation to label major areas of the flow. This is useful when a template has multiple sections, such as:

• Intake
• Review
• Approval
• Notifications
• Follow-up
• Error handling

Headers are best for high-level grouping. They should be short, clear, and easy to scan when zoomed out on the canvas.

# Note

The note annotation creates a note with general text.

Use a note annotation when you need to explain a part of the flow directly on the canvas. This can include:

• Why a state or action exists
• What data is expected at a point in the flow
• Implementation notes
• Testing notes
• Warnings about edge cases
• A short checklist for maintaining the template

Note annotations are useful for operational notes that should stay close to the related part of the template.

# Markdown

The markdown annotation creates a markdown-formatted note on the canvas.

Use a markdown annotation when the note needs richer formatting than plain text. This is useful for:

• Bulleted or numbered instructions
• Checklists
• Inline code or field names
• Links inside the note content
• Structured explanations that need headings or emphasis

Markdown annotations are best for documentation-style notes that should remain visible and readable directly on the canvas.

# Data/Text

The data/text annotation allows editing textual data on template.data directly from the canvas.

Each data/text annotation is linked to a data path. The text entered in the annotation is saved to that path in template.data, which means it can be reused elsewhere in the template with substitution.

Use a data/text annotation for editable text values such as:

• LLM prompts
• Message templates
• Instructions
• Shared snippets
• Configuration text

For example, a data/text annotation could be linked to template.data.prompts.system, making the prompt visible and editable on the canvas while still storing it in the template data structure.

# Form Fields

The form_fields annotation allows specifying a form that captures data to template data from the canvas.

Use a form fields annotation when template-level configuration needs to be edited through a structured form instead of a single text field. This is useful for grouped settings such as:

• Integration configuration
• Prompt variables
• Display settings
• Routing options
• Reusable template defaults

The captured values are saved into template.data, making them available to actions, tasks, layouts, and substitution throughout the template.

# Media Link

The media_link annotation allows an image to be placed on the canvas.

Use a media link annotation when a visual reference helps explain the flow. This can include:

• Screenshots
• Diagrams
• Mockups
• Logos
• Example outputs

Media link annotations are useful when the visual context is part of how the template should be understood or maintained.

# Sticker

The sticker annotation marks areas of the canvas with a preset status label.

Available stickers include:

• WIP
• REVIEW
• FIX
• IMPROVE
• DEPRECATED
• NEW

Use stickers to make work status visible at a glance. They are useful for marking incomplete sections, areas that need review, known problems, improvement opportunities, deprecated parts of a flow, or newly added sections.

# Best Practices

• Keep annotations close to the states, actions, or connections they describe.
• Use headers to divide large flows into clear regions.
• Use URL annotations for references that are likely to change or need to be opened often.
• Use markdown annotations when formatting improves readability.
• Use data/text and form_fields annotations when the canvas should act as an editor for template.data.
• Use stickers consistently so their meaning stays clear across the team.
• Keep text annotations concise. If the explanation is long, use markdown or link to a document using a URL annotation.
• Update annotations when the flow changes so they do not become misleading.

# Example Layout

A template flow might use annotations like this: