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.

Note: Applying debug settings applies them to the current session. To keep these settings after closing the editor, you must save the runbook separately.

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.

Leaving debug enabled in production runbooks can significantly impact performance. For example, in ServiceNow subflows, execution speed can decrease by an order of magnitude (execution can be 10x slower) when debug is enabled. Always disable debug before saving production runbooks.

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.

    • Request Headers: All HTTP request headers (collapsed by default).

    • Request Body: The request payload/body content (expanded by default).

  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.

Expanded Subflow Debug Information

The Debug Runbook Flow dialog shows detailed information about nodes that execute inside subflows. You can see the execution path and status of individual nodes within the subflow.

When viewing a subflow node in the Debug Runbook Flow dialog, you can:

  • View the parent runbook context to understand how the subflow fits into the larger runbook execution.

  • Drill into the subflow to see the detailed execution path of nodes within the subflow.

  • Replace the current view with the subflow's internal execution flow for focused troubleshooting.

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.