The Workflow Canvas
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- CONTRIBUTING.md
- packages/testing/playwright/CONTRIBUTING.md
- packages/testing/playwright/composables/CanvasComposer.ts
- packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts
- packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/utils/test/markdown-workflow.utils.test.ts
The Workflow Canvas is the primary user interface for creating, editing, and managing automation workflows within the n8n platform. It provides a visual, node-based environment where users can drag and drop nodes, connect them to define data flows, and configure their parameters. The entire frontend, including the canvas, is built using Vue 3.
The canvas is located in the packages/frontend/editor-ui module and serves as the central hub for all workflow-related interactions. It supports a rich set of features including creating and connecting nodes, saving and publishing workflows, executing and debugging, and managing the overall workflow lifecycle.
Sources: CONTRIBUTING.md:20-24, AGENTS.md:46-47
Architecture and Core Components
The canvas is a composite Vue component that orchestrates several child components to render a complete workflow. The main architectural pieces are the canvas itself, the nodes, and the connections (edges) between them.
This diagram shows the basic component hierarchy for the visual elements on the canvas.
Canvas Nodes
Nodes are the fundamental building blocks of a workflow. Each node represents a specific action, trigger, or logic block. In the UI, a node is represented by a CanvasNode.vue component. Test files identify nodes using a data-test-id="canvas-node" attribute and a data-node-name attribute for specific identification.
Sources: packages/testing/playwright/CONTRIBUTING.md:52-54
Key properties of a node as represented on the canvas include:
| Property | Description | Source |
|---|---|---|
id | A unique identifier for the node instance within the workflow. | packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts:143-151 |
name | The user-defined name of the node. | packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:119-122 |
type | The node's type identifier (e.g., n8n-nodes-base.httpRequest). | packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts:146 |
position | An array [x, y] defining the node's coordinates on the canvas. | packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts:148 |
parameters | An object containing the node's configuration. | packages/@n8n/ai-workflow-builder.ee/src/tools/utils/test/markdown-workflow.utils.test.ts:21-22 |
disabled | A boolean indicating if the node is disabled. | packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:98-106 |
status | Visual indicators such as pinned or error. | packages/testing/playwright/CONTRIBUTING.md:60-62 |
Canvas Connections (Edges)
Connections, or edges, link nodes together to define the flow of execution and data. They are rendered by a CanvasEdge.vue component. Connections are established between specific input/output handles on the source and target nodes.
There are two primary types of connections:
- Main Connections: Represent the standard data flow from a source node's output to a target node's input.
- AI Connections: Special connections used in AI workflows to link sub-nodes (like tools, memory, or language models) to a primary AI Agent node. These are typically prefixed with
ai_.
The diagram below illustrates the different connection types found in workflows.
Canvas Operations
A rich set of operations can be performed on the canvas, either through UI interactions or keyboard shortcuts. These operations are encapsulated and tested in composables like CanvasComposer.ts.
Common User Actions
| Action | Keyboard Shortcut | Description | Source |
|---|---|---|---|
| Save Workflow | Ctrl/Cmd + S | Saves the current state of the workflow. | packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:46-53 |
| Execute Workflow | F8 (or platform equivalent) | Runs the entire workflow manually. | packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:360-363 |
| Rename Node | F2 | Opens a prompt to rename the selected node. | packages/testing/playwright/composables/CanvasComposer.ts:111-118 |
| Select All | Ctrl/Cmd + A | Selects all nodes on the canvas. | packages/testing/playwright/composables/CanvasComposer.ts:39-42 |
| Copy | Ctrl/Cmd + C | Copies selected nodes to the clipboard as JSON. | packages/testing/playwright/composables/CanvasComposer.ts:32-36 |
| Paste | Ctrl/Cmd + V | Pastes nodes from the clipboard onto the canvas. | packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:182-190 |
| Zoom In/Out | + / - | Zooms the canvas view. | packages/testing/playwright/composables/CanvasComposer.ts:71-74 |
Workflow Lifecycle Management
The canvas UI provides access to several actions that manage the entire workflow's lifecycle. These are typically found in a workflow menu.
- Save: Persists changes to the workflow. A
POSTrequest is made to/rest/workflowsfor a new workflow, and aPATCHrequest is made for an existing one. - Publish: Activates the workflow, making triggers live. This is only possible if the workflow has a trigger node and no nodes with errors.
- Unpublish: Deactivates a published workflow.
- Archive: Deactivates and archives a workflow, making it read-only.
- Delete: Permanently removes a workflow. This is only possible for archived workflows.
- Duplicate: Creates a copy of the current workflow.
Sources: packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:14-20, packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:70-76, packages/testing/playwright/tests/ui/7-workflow-actions.spec.ts:255-271
The following sequence diagram shows the process of saving a new workflow for the first time.
State and Diffing
The state of the canvas, including all nodes and connections, is reactive. When comparing different versions of a workflow (e.g., for a diff view), the useWorkflowDiff composable is used. This utility maps the nodes and connections of two workflow versions and computes the differences.
The mapConnections function within this composable is responsible for creating a Map and Set of connection IDs for efficient lookup and comparison. This allows the system to identify added, deleted, or modified connections between two workflow states.
Nodes are identified as Added, Deleted, Modified, or Eq (equal) based on their presence and content across the two versions. This status is then used to visually highlight changes on the canvas.
Sources: packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts:11-13, packages/frontend/editor-ui/src/features/workflows/workflowDiff/useWorkflowDiff.test.ts:211-218
Testing the Canvas
The Workflow Canvas and its interactions are extensively tested using Playwright for end-to-end (E2E) testing. The testing architecture follows a four-layer approach to ensure separation of concerns and maintainability.
- Tests (
.spec.ts): Define high-level user scenarios (e.g., "should publish workflow"). - Composables (
CanvasComposer.ts): Orchestrate complex, multi-step business workflows on the canvas (e.g.,pinNodeData,saveWorkflowAndWaitForUrl). - Page Objects (
CanvasPage.ts): Encapsulate UI interactions and element locators specific to the canvas (e.g.,clickExecuteWorkflowButton,nodeByName). - BasePage: Provides generic helper methods like
clickByTestId.
This layered approach makes tests more readable and resilient to UI changes.
Sources: packages/testing/playwright/CONTRIBUTING.md:29-37, packages/testing/playwright/composables/CanvasComposer.ts:5-7