Runbook Debugging Features

IQ Ops provides many features that make it easier to troubleshoot runbooks, understand execution flow, and identify issues. Use these features when you need to debug failed runbook executions, trace execution paths, or diagnose configuration problems. These features make it easier to enable and disable debug, provide clearer visual indicators, and offer more readable debug output.

Debug Configuration Dialog

The Runbook Editor toolbar includes a debug configuration tool that opens a dialog for managing debug settings across all nodes in your runbook. This dialog makes it easier to enable or disable debug on multiple nodes at once, rather than configuring each node individually.

Using the Debug Configuration Dialog

To open the debug configuration dialog:

1. In the Runbook Editor, click the debug icon in the toolbar.

2. The debug configuration dialog opens, showing all nodes in your runbook listed alphabetically.

Dialog Features

The debug configuration dialog provides the following features:

• Alphabetical node listing: All nodes are displayed in alphabetical order to make navigation easier.

• Clear node identification: Each node displays its category and type (for example, Data Queries > Applications) to help you identify the correct node.

• Bulk operations: Use the "Uncheck All" link at the bottom right to quickly disable debug on all nodes.

• Enable All Highlighted: If you have selected nodes on the canvas before opening the dialog, an Enable All Highlighted link appears. Clicking this link enables debug for all the nodes you selected on the canvas.

After making your selections, click Apply to save your debug settings.

Visual Indicators for Debug Status

Visual indicators make it immediately obvious when debug is enabled on nodes, helping you avoid leaving debug unintentionally enabled in production runbooks.

Node Canvas Indicators

When you enable debugging on a node, a Debug flag appears on the corner of that node in the Runbook Editor canvas.

Save Dialog Warning

When you click Save in the Runbook Editor to save a runbook that has any nodes with debugging enabled, the Save Runbook dialog highlights that debugging is enabled and provides a quick way to disable it before saving. This warning only appears when at least one node has debugging enabled.

Debug Output Readability

Debug output provides more readable, formatted information that is easier to understand and troubleshoot. Instead of viewing raw JSON or text data, you now see specialized formatted debug output tailored to each node type.

Debug Output Tabs

When viewing debug information for a node in the Debug Runbook Flow dialog, you have two tabs:

• Inspect tab: Formatted, structured debug output that presents information in an organized, easy-to-read format. The Inspect tab is the default view and provides the most user-friendly presentation of debug data.

• Debug tab: Raw debug output in text format. Use this tab when you need to see the unformatted debug data.

Transform Node Inspect Tab

The Transform node provides a specialized Inspect tab that organizes transform debug data into structured sections. This enhanced debug view displays transform input/output data with automatic validation of the rendered Liquid template against the expected output data format.

The Transform node Inspect tab organizes debug data into the following sections:

1. Error and Warning banners: When a transform error is reported, an error banner is displayed at the top of the tab using red/danger styling for immediate visibility. Validation findings are displayed as warning banners with yellow/orange background.

2. Inbound Entity Section: The input data that was passed to the transform node. This section is collapsed by default.

3. Rendered Template Section: The output data after the Liquid template has been rendered. This section is expanded by default.

Additional features:

• Copy to Clipboard: Each section includes a copy button to quickly copy section content.

• Collapsible Sections: All sections, except for top banners, can be expanded/collapsed individually.

• Conditional Display: Each section is displayed only if data is available for it.

HTTP Node Inspect Tab

The HTTP node provides a specialized Inspect tab that displays formatted, structured views of HTTP request/response data. The Inspect tab displays data in a collapsible tree view format, with JSON data automatically formatted for readability.

The HTTP node Inspect tab organizes debug data into the following sections:

1. Error banner: When an error is reported, an error banner is displayed at the top of the tab using red/danger styling for immediate visibility.

2. Request Section:

   • Request Overview: Displays HTTP method (GET, POST, PUT, DELETE, etc.) and full URL. Variables in the URL are resolved to their actual values.

   • Request Headers: All HTTP request headers (collapsed by default). Variables in headers are resolved to their actual values.

   • Request Body: The request payload/body content (expanded by default). The request body template is shown after rendering, with all variables resolved to their actual values.

3. Response Section:

   • Response Status: HTTP status code with color-coded badge. Green (2xx), Yellow/Orange (3xx), Red (4xx/5xx).

   • Response Headers: All HTTP response headers (collapsed by default).

   • Response Body: The response payload/body content (expanded by default).

Additional features:

• Copy to Clipboard: Each section includes a copy button to quickly copy section content.

• Collapsible Sections: All sections, except for the error banner and request overview, can be expanded/collapsed individually.

• Conditional Display: Each section is displayed only if data is available for it.

Error Messages

Debugging error messages have clear, descriptive messages that explain what went wrong and, when applicable, what you can do to fix the issue.

Error messages may include:

• Underlined text that indicates clickable links to related configuration pages or documentation. For example, a link might take you directly to the integration configuration page where you can fix the issue.

• Bracketed text that indicates variable names or values that were involved in the error. For example, you might see [variable_name] or [value] to show which variable or value caused the problem.

• Specific guidance on how to resolve the issue.

For a full list of debugging error codes, see Runbook Debug Error Codes.

Subflow Debugging

Debugging capabilities have been enhanced for runbooks that use subflows, making it easier to troubleshoot issues that occur within subflow execution.

Subflow Debug Tree View

The Debug Runbook Flow dialog shows detailed information about nodes that execute inside subflows. Instead of displaying raw runbook output, the UI creates a sanitized tree view that makes it easier to understand subflow execution:

• Node labels as primary identifiers: Node labels are shown as the primary label in the tree view, making it easier to identify nodes.

• Removed unnecessary fields: Technical details like node IDs are removed from the display to reduce clutter.

• Human-readable timestamps: UNIX timestamps are converted to human-readable timestamps or execution duration.

• Standard Inspect view: When you select a node within a subflow, the standard Inspect view (used for regular runbook nodes) is displayed, providing consistent debugging information across all node types.

Node Selection in Subflows

When viewing a subflow node in the Debug Runbook Flow dialog, you can select individual nodes from within the subflow. The node selection list is sorted by execution start time and includes:

• An icon representing the node type (same icon used in the Runbook Editor)

• The node label

• The execution status of the node

• The execution duration of the node

Authentication Error Context

When authentication-related errors occur during subflow execution, the error messages include integration context information (such as the integration name, authentication profile name, and connection details) that helps you understand which integration or authentication profile was involved in the error. This makes it easier to identify and resolve authentication configuration issues. The debug information is also shown for the subflow's internal node that is selected in the dropdown.