5.4 Workflow Best Practices
      Back to home
      1. Home
      2. 5. Workflows & Automation
      3. 5.4 Workflow Best Practices

      Workflow Debugging & Troubleshooting

      Identifying and resolving issues in your Rayven workflows using the built-in tools and best practices.

      Overview

      Debugging workflows is a critical part of application development in Rayven. Whether you're building a complex integration pipeline or a simple automation, being able to inspect what’s happening at each step is essential. This guide walks you through the tools and techniques available in Rayven for troubleshooting workflow issues, inspecting data payloads, and improving workflow reliability.

      Tools for Debugging Workflows

      Rayven provides two main tools for inspecting data within workflows:

      1. Inspect Data Tab (Available on All Nodes)

      Each workflow node has an Inspect Data tab that allows you to view:

      • The incoming payload to the node

      • The outgoing payload from the node

      You can filter the displayed payloads by:

      • UID

      • Date range

      • Text contents

      🖼️ [Add Screenshot: Example of a node showing its Inspect Data tab with filters]

      This is most useful for:

      • Verifying whether a node is receiving data

      • Confirming how a node is transforming or passing data

      • Debugging logic within that specific node

      2. Inspect Data Node (Standalone Workflow Node)

      The Inspect Data node is a workflow node that you can place anywhere in a workflow to capture and view payloads being passed through it. You can flow any data you like into this node—whether for logging a specific step, debugging a junction in logic, or isolating a data anomaly.

      This makes it especially helpful for:

      • Centralised debugging (flow different branches of data into a single Inspect node)

      • Capturing snapshots of transformed payloads

      • Verifying conditional branches or rule outcomes

      ✅ Best Practice: Use Inspect Data nodes during build and debugging phases, then remove or disable them before production to reduce unnecessary data flow.


      Common Debugging Techniques

      1. Start Small and Isolate the Problem

      When building a complex workflow, begin with a minimal working version and add components gradually. This makes it easier to pinpoint where issues are introduced. Test and verify each node before layering on more complexity.

      2. Use “Inspect Data” Tab Frequently

      Open the Inspect Data tab in each node as you build. This lets you:

      • Confirm whether the payload contains the required structure and expected values

      • Verify whether the logic or transformation in that node is functioning correctly

      🔍 Tip: Remember, this tab only shows payloads entering and exiting that specific node.

      3. Use Inspect Data Nodes for Broader Visibility

      The Inspect Data node is a standalone node you can place anywhere in a workflow. Unlike the Inspect tab (which is node-specific), this node captures whatever data you route into it. Use it to:

      • Inspect payloads from different branches of logic

      • Capture intermediate data before table writes or external calls

      • Debug conditional outcomes and rule branches

      ✅ Best Practice: Use Inspect Data nodes liberally while developing and debugging workflows. Remove them when deploying to production unless ongoing monitoring is needed.

      4. Validate Incoming Payloads Early

      Place a JavaScript or Conditional Filter node early in your workflow to:

      • Validate key fields are present

      • Catch malformed or incomplete data

      • Route unexpected data to a separate path for inspection

      5. Temporarily Simplify Logic

      If you're unsure where a failure is occurring:

      • Replace complex logic with hardcoded values or test inputs

      • Disable branches of logic or unnecessary nodes temporarily

      • Focus on one transformation or action at a time

      This lets you narrow down where the issue lies before restoring full functionality.

      6. Validate Iterative Workflows Carefully

      When your workflow runs iteratively (per UID or per label group):

      • Confirm the Trigger or Connector node is configured to use the correct "Trigger using filter" setting

      • Make sure the filter criteria match actual label values in your Primary Table

      • Use Inspect Data to ensure each iteration receives a complete payload

      7. Check Frontend Node Input & Settings

      If a widget is not showing data on the App Interface:

      • Confirm the Frontend node received data (Inspect Data tab)

      • Verify the "Number of Widgets to Display" setting matches your label or UID setup

      • Check whether the node is performing aggregation or filtering correctly

      📌 Note: Data is only stored in a node after it receives payloads. Adding a new Frontend node won't auto-populate it with historical data.

      Debugging Frontend Behaviour

      Sometimes an interface widget doesn't display data as expected. Use the following checks:

      • Is the Frontend node included in a workflow?

      • Has data been passed through the node since it was added? (Historical data is not automatically shown)

      • Are the “Number of Widgets to Display” settings correct?

      • Is the user’s label filter restricting visibility?

      Handling Empty or Incorrect Table Writes

      If you're writing to a table but data isn't appearing:

      • Check Update Table Node Output
        This node will confirm what data was written (although it doesn't return the actual table contents).

      • Confirm UID or Key Column Usage
        If no matching UID or key column is found, a new row will be created. Make sure this is intended behaviour.

      • Inspect Payload Before Writing
        Use a JavaScript or Data Summary node before the Update Table node to inspect and log what values are about to be written.

      Summary

      Debugging workflows in Rayven involves inspecting data payloads at each node and verifying that each step is producing the intended result. 

      Rayven provides two essential debugging tools:

      • Inspect Data tab: view data entering and leaving a specific node

      • Inspect Data node: capture any data flowing through a workflow

      Together, these tools give developers excellent visibility into how workflows behave, enabling precise and efficient debugging. Use Inspect nodes liberally during development, and inspect each step as you build for more predictable, maintainable workflows.

      FAQs

      What’s the difference between the Inspect Data tab and the Inspect Data node?
      The Inspect Data tab is built into every node and shows only the data entering and exiting that specific node. The Inspect Data node is a standalone node you can insert anywhere in the workflow to capture and inspect any data passed into it—regardless of origin.

      When should I use the Inspect Data node instead of the tab?
      Use the Inspect Data node when you want to debug data at specific points in the workflow—such as after branching logic, before writing to a table, or when comparing multiple payload paths. It’s especially useful for isolating and inspecting custom logic outcomes.

      How do I inspect data flowing through a workflow?
      Use the Inspect Data tab on each node to view incoming and outgoing payloads. You can filter by UID, time range, or content. For broader visibility, insert Inspect Data nodes into the workflow wherever you want to manually inspect payloads.

      What’s the best way to test a new workflow?
      Start with a simple version and known data. Use Inspect Data tabs or nodes frequently during build. Test iteratively and validate each step before adding more complexity.

      Why is my Frontend widget not displaying data?
      Ensure that the Frontend node received data after it was added to the workflow—data must be passed through the node to be stored. Also verify the “Number of Widgets to Display” setting and label configuration are appropriate for the expected output.

      What if my Frontend widget is blank?
      Check the node’s Inspect Data tab to confirm it received payloads. Confirm that the data is structured correctly and that widget display settings (e.g. label groupings, UID mappings) match your data.

      How do I verify what data was written to a table?
      You can view the contents of any table directly in the Tables section of the Workspace. This lets you inspect all rows, check field values, and even manually edit data. 

      Can I use the Inspect Data node in production?
      Technically yes, but it’s not recommended. The Inspect Data node is designed for debugging and development. To reduce unnecessary processing and improve clarity, remove or disable it before going live.

      My iterative workflow isn’t running for each row—why?
      Make sure your Trigger or Connector node is set to run iteratively using the “Trigger using filter” option. Also check that label values or UIDs used in the filter match actual records in your Primary Table.