Workflows, Nodes, and Connections

Relevant source files

The following files were used as context for generating this wiki page:

• packages/workflow/src/interfaces.ts
• packages/nodes-base/nodes/Start/Start.node.ts
• packages/frontend/editor-ui/src/constants.ts
• packages/nodes-base/nodes/Github/Github.node.ts
• packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json
• packages/testing/playwright/tests/ui/1-workflows.spec.ts
• CLAUDE.md

Workflows are the core of the n8n platform, representing a series of connected steps to automate a process. They are composed of nodes, which perform individual actions, and connections, which define the flow of execution and data between these nodes. This system allows for the creation of complex automations by linking together various services and custom logic.

The n8n project is a monorepo with key packages defining this architecture. The packages/workflow directory contains the core interfaces, packages/nodes-base provides the built-in nodes, and packages/editor-ui includes the frontend application for building and managing workflows.

Sources: CLAUDE.md

Workflows

A workflow is a JSON object that encapsulates all the necessary information for an automation, including its nodes, their connections, and various settings.

Workflow Structure

A workflow is defined by a specific JSON structure containing nodes, connections, and metadata. The example below from a tutorial workflow illustrates the basic layout.

{
	"name": "Expressions",
	"nodes": [
		{
			"id": "2c20bdef-e54e-46ab-9c63-5cf521ec749e",
			"name": "Start Tutorial",
			"type": "n8n-nodes-base.manualTrigger",
			"position": [-7360, 992],
			"parameters": {},
			"typeVersion": 1
		},
		{
			"id": "b875f86c-a790-49bc-96a0-e1ccc72a5e80",
			"name": "Source Data",
			"type": "n8n-nodes-base.set",
			"position": [-6720, 992],
			"parameters": { ... }
		}
	],
	"connections": {
		"Start Tutorial": {
			"main": [
				[
					{
						"node": "Source Data",
						"type": "main",
						"index": 0
					}
				]
			]
		}
	}
}

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json

The main properties of a workflow are detailed below:

Property	Type	Description	Source File
name	string	The user-defined name of the workflow.	packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json
nodes	INode[]	An array of node objects that make up the workflow.	packages/workflow/src/interfaces.ts:1020
connections	IConnections	An object defining the connections between nodes.	packages/workflow/src/interfaces.ts:1021
active	boolean	A flag indicating if the workflow is active.	packages/testing/playwright/tests/cli-workflows/workflows/91.json:5
id	string	A unique identifier for the workflow.	packages/testing/playwright/tests/cli-workflows/workflows/91.json:3
tags	ITag[]	An array of tags associated with the workflow for organization.	packages/workflow/src/interfaces.ts:1023
settings	IWorkflowSettings	Settings for the workflow, such as error handling.	packages/workflow/src/interfaces.ts:1022
meta	IWorkflowMeta	Metadata about the workflow, such as templateId.	packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json:3
pinData	IWorkflowPinData	Data pinned to specific nodes for debugging or reference.	packages/workflow/src/interfaces.ts:1025

Workflow Management and Lifecycle

Workflows can be managed through the UI or API. End-to-end tests demonstrate the typical lifecycle of a workflow, which includes creation, saving, searching, archiving, and deletion.

The following diagram illustrates the lifecycle of a workflow.

This diagram shows the various states a workflow can be in, from creation to deletion.

Sources: packages/testing/playwright/tests/ui/1-workflows.spec.ts

Key management actions include:

• Create: New workflows can be created from a blank state or from templates.
• Save: A workflow's name and structure are persisted. The default name for a new workflow is "My workflow".
• Search & Filter: Workflows can be searched by name or filtered by tags.
• Archive: Inactive workflows can be archived to hide them from the main list.
• Delete: Archived workflows can be permanently deleted.

Sources: packages/testing/playwright/tests/ui/1-workflows.spec.ts, packages/frontend/editor-ui/src/constants.ts:40

Nodes

Nodes are the fundamental building blocks of a workflow. Each node performs a specific task, such as triggering the workflow, manipulating data, or integrating with an external service.

Node Definition

A node is defined by an INodeType implementation, which includes a description object and an execute method. The description contains metadata that the UI uses to render the node and its parameters.

The diagram below shows the key components of a node's description property.

This class diagram outlines the structure of the INodeTypeDescription interface, which defines a node's metadata.

Sources: packages/nodes-base/nodes/Github/Github.node.ts:25-59

A node's implementation file, typically ending in .node.ts, contains the logic. For example, the Github.node.ts file defines the GitHub node's behavior, including its operations and how it interacts with the GitHub API.

Key properties in the node description include:

Property	Description	Example from Github.node.ts
displayName	The human-readable name shown in the UI.	'GitHub'
name	The internal, unique name for the node type.	'github'
group	The category group for the node in the UI.	['input']
version	The version(s) of the node.	[1, 1.1]
inputs / outputs	Defines the connection points and their types.	[NodeConnectionTypes.Main]
credentials	Specifies the required credentials for the node.	githubApi, githubOAuth2Api
properties	An array of objects defining the node's parameters and UI fields.	authentication, resource, operation, etc.

Sources: packages/nodes-base/nodes/Github/Github.node.ts:25-1085

Node Types

n8n includes a wide variety of node types, which can be broadly categorized.

• Trigger Nodes: These nodes start a workflow. They can be manual, scheduled, or triggered by a webhook. Examples include n8n-nodes-base.start, n8n-nodes-base.webhook, and n8n-nodes-base.cron. Some triggers are executable directly from the editor (e.g., Start), while others like Webhook must be activated to listen for external events.
• Regular Nodes: These nodes perform actions on data passed to them. They form the main logic of a workflow. Examples include n8n-nodes-base.httpRequest for making API calls, n8n-nodes-base.set for manipulating data, and n8n-nodes-base.if for conditional logic.
• Core Nodes: A sub-category of nodes that provide fundamental building blocks for data transformation and flow control, such as n8n-nodes-base.function and n8n-nodes-base.merge.
• Special Nodes: The n8n-nodes-base.stickyNote node is a unique type used for adding comments and documentation directly onto the workflow canvas.

Sources: packages/frontend/editor-ui/src/constants.ts:125-240, packages/nodes-base/nodes/Start/Start.node.ts, packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json:20

Node Execution

The core logic of a node is contained within its execute method. This method is called by the n8n engine when the workflow execution reaches the node.

The general flow of execution within a node is as follows:

1. Receive input data from previous nodes.
2. Iterate through the input items.
3. For each item, read node parameters.
4. Perform the node's primary action (e.g., make an API call, run custom code).
5. Format and return the output data.

The Github.node.ts execute method demonstrates this by looping through input items, determining the selected resource and operation, constructing an API request to GitHub, and then returning the response data.

This flowchart depicts the typical execution process within a single n8n node.

Sources: packages/nodes-base/nodes/Github/Github.node.ts:1100-1550

Connections

Connections link nodes together, defining the path of execution and the flow of data through the workflow.

Connection Structure

In the workflow's JSON representation, connections are defined in a connections object. The keys of this object are the names of the source nodes. The value is an object that maps an output name (e.g., main) to an array of target nodes.

"connections": {
    "Start Tutorial": {
        "main": [
            [
                {
                    "node": "Source Data",
                    "type": "main",
                    "index": 0
                }
            ]
        ]
    }
}

This structure indicates that the main output of the "Start Tutorial" node is connected to the main input of the "Source Data" node.

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json:298-312, packages/workflow/src/interfaces.ts:80-92

Connection Types

n8n supports different types of connections to handle various data and logic flows, particularly for AI and complex workflows. The NodeConnectionType enum defines these types.

Connection Type	Description
Main	The standard connection for data flow between most nodes.
AiTool	Connects a tool to an AI agent.
AiChain	Connects nodes in a LangChain chain.
AiModel	Connects a language model to an AI node.
AiMemory	Connects a memory module to an AI node.
AiOutputParser	Connects an output parser to an AI node.

The Main and AiTool connection types are configured to allow multiple connections from a single output.

Sources: packages/workflow/src/interfaces.ts:13-28, packages/frontend/editor-ui/src/constants.ts:316-319

Data Flow

Connections enable data to flow from one node to the next. A downstream node can access the output data of an upstream node using expressions. For example, a Set node might use the expression {{ $('Source Data').item.json.name }} to access the name field from the output of a node named "Source Data".

The diagram below shows the data flow in the "Expressions Tutorial" workflow.

This graph illustrates how data from the Source Data node is accessed and used in subsequent nodes via expressions.

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/expressions_tutorial.json:80-89, 298-320