Control Any n8n Workflow With a Custom UI — Step by Step Guide

This video demonstrates how to use custom user interfaces to control NAN workflows, focusing on interactive elements during workflow execution, rather than just post-completion dashboards.

Custom UI for Interactive Workflows

The core concept is to break down a workflow into discrete steps that can be controlled by user input from a custom interface. This allows users to interact with the workflow at various stages, providing information or making choices that influence its progression.

Key Differentiator: Unlike typical "AI operating system" dashboards that display completed workflow executions and metrics, this approach focuses on building interfaces that allow users to actively participate while the workflow is running.

Demo Workflow: Claims Portal

A practical example is presented: a customer portal for managing claims.

• Initial Step: The workflow starts by waiting for a user to upload a PDF (e.g., an invoice).
• Document Analysis: The uploaded document is analyzed to extract product information.
• Agent Interaction: This information is fed into an AI agent to generate initial options for the customer.
• User Selection (Weight Node 1): The workflow pauses at a "weight node," presenting these options to the user on the custom interface. The user selects a product (e.g., MacBook Pro) and a claim type (e.g., warranty claim).
• Further AI Processing: The user's selection is sent back into the workflow, processed by another AI agent, which generates more specific options.
• User Selection (Weight Node 2): The workflow pauses again, presenting these refined options (e.g., specific troubleshooting steps for a warranty claim). The user selects relevant issues (e.g., "Battery is not charging," "Screen is flickering").
• Troubleshooting and Information Gathering: The workflow provides troubleshooting steps and requests the user's email address.
• Email Notification: Upon submission, an email is sent to the user with a summary of their claim and confirmation of progress.

Custom Interface Features: Throughout this process, the custom UI displays dynamic information such as:

• Invoice preview.
• Warranty eligibility status.
• Summary of invoice contents.
• Submission history.

The Power of the "Weight Node"

The "weight node" is central to enabling these interactive workflows.

• Functionality: It pauses workflow execution, allowing for user input from an external interface.
• State Management: When paused, the weight node offloads all execution data to the NAN database. This means the workflow remains live and can be resumed at any time (hours, days, or even years later), with all previously generated variables and data preserved.
• Resilience: This ensures that even long-running or interrupted workflows maintain their state.
• API Interaction: The data stored can be retrieved via the NAN API using the workflow's unique ID.

Methods for Pausing and Interacting with Workflows

The video outlines two primary native NAN methods for creating stop-and-start interfaces, and then discusses custom coding:

1. NAN Forms:

   • Process: Uses a sequence of "form" nodes. A trigger starts the workflow, followed by processing steps. The "next form" node allows for dynamic creation of subsequent form pages, enabling users to input information sequentially.
   • Limitations: While it allows for dynamic content, it's more limited in terms of visual design and interactivity compared to custom-coded solutions. It cannot achieve "flashy colors" or complex animations.

2. Human in the Loop Nodes (e.g., Gmail, Slack, WhatsApp):

   • Process: These nodes pause the workflow and send messages to users via various platforms (Slack, Gmail, etc.), waiting for a response before resuming.
   • Mechanism: They essentially use webhook calls to communicate with external services and wait for a reply.
   • Underlying Infrastructure: The weight node's infrastructure is likely the foundation for these human-in-the-loop nodes, as they all involve pausing execution and waiting for external input.

3. Custom Coding (e.g., using Cursor or Lovable):

   • Advantage: Offers complete control over the user interface's appearance and interactivity, allowing for complex designs and dynamic elements.
   • Process: Involves building the UI separately and connecting it to NAN via webhooks.

Webhook Calls and the execution.resume_url

• Webhooks: The fundamental mechanism for external applications to communicate with NAN workflows. They involve sending data to a specific URL (the webhook endpoint) and receiving a response.
• execution.resume_url: A crucial dynamic variable generated at runtime when a NAN workflow starts. This URL is the specific endpoint that the custom interface needs to target to send information back to a paused weight node.
• Dynamic Generation: The execution.resume_url is created as soon as the workflow begins, even before a weight node is encountered. It's essential for resuming the workflow.
• Usage: The custom UI needs to capture this URL and use it as the destination for its API calls to send data back to the NAN workflow.

Building a Custom UI Workflow: Step-by-Step

1. Plan the UI:

   • Map out the different web pages or screens required for each stage of the workflow.
   • For the demo, this included a "Start Screen," "Collect Document Screen," "Present Options Screen," and a "Troubleshooting/Email Screen."

2. Design the Screens:

   • Use tools like ChatGPT to generate UI designs based on the planned screens and required functionality.
   • The designs can then be implemented using custom coding tools (e.g., Cursor for coding, Lovable for a more DIY approach).

3. Connect to NAN (The "Triad"):

   • The core connection involves a "Code Node," "Respond to Webhook Node," and a "Weight Node."
   • Code Node: Used to construct the JSON payload that will be sent back to the custom UI. This payload often includes the execution.resume_url and any relevant data generated by the workflow (e.g., summary, eligibility status, product details).
   • Respond to Webhook Node: Passes the constructed payload back to the waiting custom interface.
   • Weight Node: Receives the incoming data from the custom UI, pauses the workflow, and stores the information. It's designed to accept any data format.

4. Handling Binary Data (Files):

   • The weight node can seamlessly handle binary data, such as uploaded files. The file is accessible within the workflow (e.g., as a variable named "file") and can be processed by subsequent nodes.

Example of UI Interaction and Data Flow

• User Action: Clicks "Start Workflow" on the custom UI.
• NAN Action: Workflow starts, generates execution.resume_url.
• NAN Response: The execution.resume_url is sent back to the UI.
• User Action: Uploads a document.
• NAN Action: The document is processed, AI generates options.
• NAN Pause: Workflow pauses at a weight node, presenting options to the user.
• User Action: Selects options.
• NAN Action: The selected options are sent back to the workflow via the execution.resume_url.
• NAN Processing: Workflow continues, generates troubleshooting steps.
• NAN Pause: Workflow pauses again, presenting troubleshooting steps and requesting email.
• User Action: Submits email.
• NAN Action: Email is sent, workflow completes.

Key Concepts

• Custom User Interfaces (UI): External interfaces built to interact with and control NAN workflows.
• Interactive Workflows: Workflows designed to allow user input and decision-making during execution.
• Weight Node: A NAN node that pauses workflow execution and waits for external input, offloading data to the database.
• Webhook: A mechanism for applications to communicate with each other via API calls.
• execution.resume_url: A dynamic URL generated at runtime that serves as the endpoint for sending data back to a paused NAN workflow.
• Human in the Loop: Nodes or processes that involve human interaction to advance a workflow.
• Code Node: A NAN node used for writing custom code to construct data payloads.
• Respond to Webhook Node: A NAN node used to send responses back to a webhook caller.
• JSON Payload: A data format commonly used for sending information between applications.
• State Management: The ability of a workflow to retain its progress and data across pauses and resumptions.