Skip to content

Martini Workflow Documentation

Overview

Martini lets you add comments to a workflow to describe its purpose, behavior, return values, and more. These comments are stored in the Configuration view and surface automatically during content-assist, giving developers instant context when searching for a workflow to invoke.

What You Will Learn

  • How to add comments to a workflow
  • Best practices for writing effective workflow comments

When To Use This

Use workflow comments when you want to:

  • Document what the workflow returns or any side effects developers invoking it should be aware of
  • Build a shared or reusable workflow that others will invoke — clear comments reduce misuse and guesswork

Prerequisites

Adding Comments to a Workflow

Workflow comments are stored in the workflow's configuration and can be written in plain text or Markdown. You can add them through either the General tab or the dedicated Comments tab in the Configuration view.

Getting Started with Workflow Comments

To open the workflow configuration and add a comment:

  1. Open the Navigator view and locate the workflow you want to document.
  2. Double-click the workflow to open it in the Workflow Designer.
  3. In the Workflow Designer toolbar, click the Show the workflow configuration button.
  4. In the Configuration view, open the comment field using either of the following methods:
    • General tab — Locate the Comments field and click it to open the Markdown editor dialog.
    • Comments tab — Click the Comments tab to access the text field directly.
  5. Enter your comment. Markdown formatting is supported. Use the view buttons to switch how the editor displays your content:
    • Show source only — raw text
    • Show source and preview — split view with rendered preview
    • Show preview only — rendered output only

Expected result: Your comment is saved to the workflow configuration.

Workflow Comment Benefits and Use Cases

Workflow comments reduce onboarding friction and improve collaboration across teams. Key benefits include:

  • Faster workflow discovery — When using content-assist to search for a workflow to invoke, comments appear beside the highlighted workflow, so developers can confirm the right one without switching context
  • Reduced errors — Clear descriptions of expected inputs and outputs help developers invoke workflows correctly
  • Living documentation — Comments stay attached to the workflow and are always visible in the designer, not in a separate document
  • Team knowledge sharing — New team members can understand the purpose of existing workflows without asking the original author
  • AI agent context — AI agents like the Designer agent can use comments to understand the intent of a workflow, enabling more accurate coding assistance

Workflow Comment Best Practices

Effective workflow comments help other developers quickly understand and correctly invoke a workflow. Keep comments concise and focused on what callers need to know.

What to include:

  • A clear summary of what the workflow does and its intended use case
  • Output behavior, including conditional return values (e.g., null, empty, fallback, or path-dependent results)
  • Errors, exceptions, and failure conditions
  • Important side effects, external dependencies, or execution constraints
  • Workflow-level notes not captured in property-level comments (e.g., cross-field interactions or global assumptions)
  • If the workflow is deprecated, explain why and reference the recommended alternative

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Processes a customer refund request and updates the order status.

Behavior:
- Validates the order exists and has not already been refunded
- Processes the refund via the payment gateway
- Sends a confirmation email to the customer on success

Output:
- `refundId` is null if the order was already refunded (no error is thrown)

Errors:
- Throws `OrderNotFoundException` if the order ID does not exist
- Throws `PaymentGatewayException` if the refund request fails

Deprecated: Use `ProcessRefundV2` instead, which supports partial refunds.

Helpful Resources