Skip to content

Debugging Workflows

Overview

Martini's workflow debugging mode gives you full control over workflow execution — letting you pause at specific nodes, inspect variables, trace execution paths, and step through logic one node at a time. When you run a workflow from the Workflow Designer, it always executes in debug mode, opening the Debug view automatically so you can observe state changes in real time.

Use breakpoints to pause execution and step through your workflow node by node. Use tracepoints to silently log information without interrupting execution. Together, these tools let you isolate bugs, validate data, and understand how your workflow behaves under real conditions.

What You Will Learn

  • How to add and remove breakpoints and tracepoints on workflow nodes
  • How to use the Debug view's execution controls
  • How to monitor variables and expressions using the Watch section
  • How to manage breakpoints and tracepoints from the Breakpoints section
  • How to configure breakpoints with hit counts and conditions
  • The differences between tracepoints and logger functions
  • How debugging behaves when concurrency is involved

When To Use This

Use workflow debugging when you need to:

  • Trace a workflow execution to find where incorrect data, wrong decisions, or unexpected exceptions occur
  • Pause at a specific node to inspect variable values before they are passed downstream
  • Step through an invoked sub-workflow node by node to verify its internal logic
  • Silently collect runtime information from a workflow without pausing execution
  • Validate conditional logic by monitoring expressions evaluated step by step

Prerequisites

Before debugging workflows, ensure the following are in place:

Workflow Breakpoints

Breakpoints are markers you place on workflow nodes that pause execution when reached. When a breakpoint is hit, the Debug view shows the current call stack, all in-scope variables and their values, and any watch expressions you have configured. From there, you can step through remaining nodes one at a time.

Adding and Removing Workflow Breakpoints

Add a breakpoint directly from the Workflow Designer.

To add a breakpoint:

  1. Right-click any workflow node (excluding Trigger Nodes) on the canvas.
  2. Select Toggle Breakpoint from the context menu.
  3. A dot overlay icon appears on the node, confirming an active breakpoint is set.

To remove a breakpoint from the canvas:

  1. Right-click the node that has the breakpoint.
  2. Select Toggle Breakpoint from the context menu.
  3. The dot overlay icon disappears, confirming the breakpoint has been removed.

To remove a breakpoint from the Debug view:

  1. Open the Debug view.
  2. In the Breakpoints section, select the breakpoint entry you want to delete.
  3. Click the Delete Breakpoint button in the section toolbar, or right-click the entry and select Delete Breakpoint from the context menu.

Workflow Breakpoint Key Terms

Key terms and concepts for understanding breakpoints in workflows:

Term Definition
Breakpoint A marker set on a workflow node that pauses execution when the node is about to execute.
Dot Overlay Icon The visual indicator that appears on a node when a breakpoint or tracepoint is active.
Hit Count The number of times a node must be reached before the breakpoint triggers.
Condition An expression evaluated when the breakpoint is hit; execution pauses only if it returns true.
Active Breakpoint A breakpoint that is enabled and will trigger during workflow execution.
Inactive Breakpoint A breakpoint that has been disabled; it remains listed in the Breakpoints section but will not trigger.
Call Stack The hierarchical list of active workflow invocations visible in the Debug view when paused.
Variables Section The Debug view panel showing all in-scope variables and their current values when execution is paused.

Workflow Breakpoint Configuration Properties

Each breakpoint can be configured with conditions and hit counts through the edit wizard. Access it by right-clicking a breakpoint entry in the Breakpoints section of the Debug view and selecting Edit .

Property Example Value What It Controls
Enabled true Whether the breakpoint is active. Tick to enable, untick to disable.
Hit Count -1 The number of times the node must be executed before the breakpoint triggers.
Language Groovy The language used to write the condition expression.
Condition amount > 1000 An expression evaluated when the breakpoint is reached. Execution pauses only when this returns true. If left blank, it always pauses.

How Workflow Breakpoints Work

When you click the Run button in the Workflow Designer toolbar, the workflow always executes in debug mode and the Debug view opens automatically. If this is the first run, that workflow's debug configuration is registered in the Debug view.

When execution reaches a node with an active breakpoint, it pauses before executing that node. The Debug view updates with:

  • Call Stack — the current execution path and any invoked sub-workflows
  • Variables — all in-scope variables and their current values at that moment
  • Watch — any watch expressions you have configured, evaluated at the current paused state

From the paused state, you use execution controls to navigate through the remaining workflow. See Debug View Execution Controls for details.

If a breakpoint has a Hit Count configured, execution only pauses after the node has been reached that many times. If a Condition is configured, execution only pauses when the condition evaluates to true. This is useful for conditional bugs or loop-related issues.

You can also disable a breakpoint without removing it. In the Breakpoints section, untick the checkbox beside the breakpoint entry. The dot overlay icon on the node appears dimmed, indicating it is inactive. To locate a breakpoint's node in the Workflow Designer, double-click the entry in the Breakpoints section to open the designer and select that node.

Workflow Breakpoints Benefits and Use Cases

Breakpoints give you precise control over when and where workflow execution pauses, so you can inspect data without guessing. Instead of adding and removing log statements every time you investigate an issue, you set breakpoints, run the workflow, and see exactly what state your data is in at that exact node.

Common use cases include:

  • Inspecting the value of a mapped variable before it is passed to a service call
  • Verifying that a conditional branch is being reached with the expected input
  • Stepping through a sub-workflow to validate its internal behavior from the parent workflow
  • Debugging loops by setting a hit count to pause only on a specific iteration

Troubleshooting Workflow Breakpoint Issues

Problem Detection Cause Fix
Breakpoint was not hit during execution Workflow runs to completion without pausing Hit count not yet satisfied, or condition expression didn't return true Review the Hit Count and Condition fields in the breakpoint edit wizard. Remove or adjust conditions that prevent the breakpoint from triggering.
Double-clicking a breakpoint entry shows a "file not found" error Error dialog on double-click in the Breakpoints section The breakpoint belongs to a workflow in a different workspace Switch to the workspace that contains the workflow referenced by the breakpoint.

Workflow Tracepoints

Tracepoints are like breakpoints but do not pause workflow execution. Instead, they log information when the node is reached, letting you collect runtime data without interrupting the workflow. This makes them ideal for monitoring data flow in production-like conditions.

Adding and Removing Workflow Tracepoints

Add a tracepoint directly from the Workflow Designer canvas.

To add a tracepoint:

  1. Right-click any workflow node (excluding Trigger Nodes) on the canvas.
  2. Select Toggle Tracepoint from the context menu.
  3. A dot overlay icon appears on the node, confirming an active tracepoint is set.

To remove a tracepoint from the canvas:

  1. Right-click the node that has the tracepoint.
  2. Select Toggle Tracepoint from the context menu.
  3. The dot overlay icon disappears, confirming the tracepoint has been removed.

To remove a tracepoint from the Debug view:

  1. Open the Debug view.
  2. In the Breakpoints section, select the tracepoint entry you want to delete.
  3. Click the Delete Breakpoint button in the section toolbar, or right-click the entry and select Delete Breakpoint from the context menu.

One Debug Marker per Node

A node can only have one debug marker at a time. You cannot set both a breakpoint and a tracepoint on the same node. Setting one replaces the other.

Workflow Tracepoint Key Terms

Key terms that distinguish tracepoints from other debugging tools:

Term Definition
Tracepoint A debug marker on a workflow node that logs information when reached without pausing execution.
Print Statement The default tracepoint behavior: logs println 'WorkflowNamespace:NodeName' when the node is reached.

How Workflow Tracepoints Work

When execution reaches a node with an active tracepoint, the workflow does not pause. Instead, it evaluates and logs the tracepoint's expression. By default, the logged expression is a print statement using the workflow namespace and node name:

1
println 'my.workflow.Namespace:Node Name'

You can edit this expression using the same edit wizard as for breakpoints. Open the Breakpoints section in the Debug view, right-click the tracepoint entry, and select Edit . The Condition field in the edit wizard accepts expressions written in any of the supported languages. Since the expression does not return true, execution continues without pausing.

Tracepoints are visible and collected only during an active debug session; they are not persisted as part of the workflow definition.

Tracepoints vs. Logger Functions

Both tracepoints and logger functions can capture runtime information, but they serve different purposes:

Aspect Tracepoints Logger Functions
Code changes required No — set directly from the context menu Yes — added as nodes in the workflow logic
Persistence Temporary — applies only during the current debug session Permanent — part of the workflow definition
Visibility Only visible during a debug session Depends on the configured log level
Typical use Short-term, ad hoc investigation Long-term observability and monitoring

Troubleshooting Workflow Tracepoint Issues

Problem Detection Cause Fix
Tracepoint node also pauses execution Execution stops at the tracepoint node A condition expression was set that returns true Edit the tracepoint and clear or correct the condition expression so it does not return true.
Tracepoint log output is not visible No output in the expected log location Tracepoint is disabled or belongs to a different workspace Verify the tracepoint is enabled in the Breakpoints section. Confirm you are in the correct workspace.

Debug View Execution Controls

The Debug view provides execution controls that let you navigate through a paused workflow step by step. These controls are active while workflow execution is paused at a breakpoint.

Using Workflow Debug Execution Controls

When execution pauses at a breakpoint, the following controls are available in the Debug view toolbar:

Resume

Continues workflow execution from the current pause point until the next breakpoint is encountered or the workflow ends. Use this to skip to the next point of interest without stepping through every node.

Step Over

Executes the currently paused node and then pauses again at the next node. If the current node invokes another workflow, Step Over does not enter that workflow — it executes it as a single unit and continues. Use this to progress through a workflow without entering sub-workflows.

Step Into

Executes the currently paused node and then pauses at the next node. If the current node is an Invoke Workflow Node, Step Into enters that sub-workflow so you can debug it node by node.

Step Into Behavior in Workflows

Step Into does not enter services or functions (built-in or custom) invoked within the workflow.
It only steps into invoked workflows.

Step Out

Runs the remainder of the current sub-workflow to completion, then pauses at the node immediately following the call to that workflow in the parent workflow. If additional breakpoints exist in the remaining nodes of the current workflow, execution pauses at those breakpoints before returning to the parent.

Terminate

Stops workflow execution entirely, ending the current debug session. Use this when you want to cancel a running workflow rather than wait for it to complete.

Debug Execution Control Key Terms

Key terms for the debugging execution model:

Term Definition
Resume Continues execution until the next breakpoint or workflow end.
Step Over Executes the current node without entering any invoked workflow.
Step Into Executes the current node and enters any invoked workflow for node-by-node debugging.
Step Out Completes the current workflow and returns to the parent workflow's next node.
Terminate Stops workflow execution entirely.

Watch Expressions in Workflow Debugging

The Watch section in the Debug view lets you monitor specific variables or expressions throughout a debug session. Unlike the Variables section (which lists all in-scope variables), watch expressions let you focus on exactly the data you care about and see how it changes each time execution pauses.

Adding and Managing Watch Expressions

Watch expressions are listed in the Watch section of the Debug view.

To add a watch expression:

  1. In the Watch section toolbar, click the Add Expression button.
  2. Enter the variable name or expression you want to monitor.
  3. The expression appears in the list and is evaluated each time execution pauses.

Alternatively, right-click any existing expression entry in the Watch section, select Add Expression from the context menu, and enter your new expression.

To edit a watch expression:

  1. Double-click the expression in the Watch section, or right-click it and select Edit from the context menu.
  2. Update the expression text.

To remove watch expressions:

  • Select one or more expressions, then click the Delete Expression button in the Watch section toolbar.
  • Right-click one or more selected expressions and choose Delete Expression from the context menu.
  • To remove all expressions at once, click the Delete All Expressions button in the Watch section toolbar, or right-click any expression and select Delete All Expressions from the context menu.

How Watch Expressions Work

Each watch expression is re-evaluated every time workflow execution pauses — at a breakpoint or after a step action. This lets you track how a variable or computed value changes as the workflow progresses.

Watch expressions accept any valid expression in the configured language (such as Groovy). You can monitor individual variables, computed values, property lookups, or comparisons. This makes them particularly useful for tracking values that pass through multiple transformations across several nodes.

Watch Expression Benefits and Use Cases

Watch expressions are useful when you need targeted monitoring without sifting through every variable in scope. Use them to:

  • Track a specific variable across multiple nodes to see exactly where its value changes unexpectedly
  • Evaluate a computed expression (such as amount * taxRate) to verify business logic at each step
  • Monitor a nested property on a complex object without expanding the full variable tree each time

Debugging Concurrent Workflows

Concurrency in a workflow occurs when a single node connects to two or more downstream nodes, causing those paths to execute in parallel:

graph LR
  S["Start Node"] --> A["Node A"]
  A --> B["Node B"] --> C["Node C"]
  A --> D["Node D"] --> E["Node E"]

When debugging workflows with concurrent paths, use logger functions instead of breakpoints or tracepoints. Add logger functions on each concurrent path and/or on any nodes that execute after the paths merge to capture variable values and execution flow at those points. For a full guide, see Logging in Workflows.

graph LR
  D3["Debug Log 3"]
  S["Start Node"] --> A["Node A"]
  A --> B["Node B"] --> D1["Debug Log 1"] --> C["Node C"] --> D3
  A --> D["Node D"] --> D2["Debug Log 2"] --> E["Node E"] --> D3

Breakpoints and Tracepoints Are Not Supported in Concurrent Paths

Debugging concurrent workflow paths using breakpoints or tracepoints is not currently supported. This is planned for a future release.

Breakpoints and tracepoints set on nodes before the concurrency split work normally. However, once execution reaches the point where concurrent paths diverge, breakpoints and tracepoints on nodes within those concurrent paths or after the paths merge are ignored.

Helpful Resources