Core Concepts

Ch02 Core Concepts

Understanding n8n's six core concepts is the prerequisite for using it effectively: Workflows, Nodes, Credentials, Executions, Expressions, and Variables. This chapter explains each with concrete examples, with special focus on the Expression syntax that trips up most beginners.

Concept 1: Workflow

A workflow is n8n's fundamental unit, representing a complete automation task. Each workflow has one trigger node (deciding when to start) and any number of processing nodes (deciding what to do), connected by lines that pass data downstream.

The complete workflow lifecycle:

1. Trigger: An event is detected (schedule fires, webhook received, email arrives, etc.) and the workflow begins executing
2. Execute: Data flows from the trigger node through each processing node in sequence
3. Output: The final node completes processing, the workflow ends, and results are written to the target system

Workflows have three runtime states: Active (responding to triggers), Inactive (paused), and Error (last execution failed).

Workflow JSON: The complete workflow definition is stored as JSON. Export it from the editor via ⋮ → Export. The JSON includes all node configs and connections and can be imported into any n8n instance.

Concept 2: Node

A node is a workflow building block — an operation unit that receives upstream data (Input), performs some action, and outputs results (Output) for downstream nodes.

Node Type Categories

Node Data Structure

All n8n node inputs and outputs are JSON arrays, where each element is called an Item. Understanding this is the foundation for mastering expressions:

// RSS Feed node output: array of 2 news items
[
  {
    "json": {
      "title": "OpenAI Releases GPT-5",
      "link": "https://example.com/gpt5",
      "pubDate": "2025-04-25T10:00:00Z",
      "content": "OpenAI today announced..."
    }
  },
  {
    "json": {
      "title": "Anthropic Releases Claude 4",
      "link": "https://example.com/claude4",
      "pubDate": "2025-04-24T14:30:00Z",
      "content": "Anthropic announced..."
    }
  }
]

By default, when a node receives multiple items it processes each one separately (like a forEach loop). If the upstream node outputs 10 RSS items, the next node runs 10 times — once per item.

Concept 3: Credentials

Credentials are n8n's mechanism for securely managing API keys and account info for third-party services. All credentials are AES-256 encrypted and never appear in execution logs.

The key benefit is cross-workflow reuse: add your OpenAI API key once in the Credentials panel, and every OpenAI node across all your workflows can reference it without re-entering it. Rotate the key in one place and all workflows instantly use the new value.

Security note: Never paste an API key directly into a regular text field in a node configuration — always manage it through the Credentials system. Execution logs record node input/output data, so a key in the data flow would be logged in plaintext.

Concept 4: Executions

Every time a workflow runs it produces an execution record capturing: timestamp, status, and the input/output data of every node. Execution records are the primary debugging tool.

Three execution states: Success (all nodes completed), Error (a node threw an exception), Waiting (workflow paused at a Wait node awaiting an external signal).

Clicking any record in the execution list opens the node view for that run, showing exactly what data each node processed — invaluable for debugging data flow issues.

Concept 5: Expressions

Expressions are n8n's most powerful — and most confusing for beginners — feature. They let you reference upstream node data, execute JavaScript logic, and access environment variables from any node config field.

Expression Syntax Basics

n8n expressions are written inside double curly braces: {{ expression }}. In a node config field, click the = button on the right to switch to expression mode.

// Reference current item's data (most common)
{{ $json.title }}                      // title field of the current item
{{ $json.user.email }}                 // nested field access
{{ $json["order-id"] }}                // bracket notation for special chars

// Reference a specific upstream node's output
{{ $node["HTTP Request"].json.data }}  // data field from "HTTP Request" node
{{ $node["Set"].json.userId }}

// Built-in variables
{{ $now }}                             // current time (DateTime object)
{{ $now.toISO() }}                     // ISO 8601 timestamp
{{ $now.format("YYYY-MM-DD") }}        // formatted date: 2025-04-25
{{ $runIndex }}                        // current item index in loop (0-based)

// JavaScript expressions
{{ $json.price * 1.1 }}                // arithmetic: price + 10%
{{ $json.name.toUpperCase() }}         // string operation
{{ $json.tags.join(", ") }}            // array to string
{{ $json.amount > 1000 ? "large" : "normal" }}  // ternary

Common Expression Reference

Expression vs Fixed Value: Node config fields default to "fixed value" mode — whatever you type is passed as-is. Click the = icon to switch to expression mode. The most common beginner mistake is forgetting to switch, causing {{ $json.title }} to be passed as a literal string.

Concept 6: Variables

n8n provides two types of variables for sharing data across workflows or executions:

Global Variables

Defined in Settings → Variables, accessible in all workflows via {{ $vars.varName }}. Good for: environment identifiers, shared API base URLs, notification email lists, business constants.

{{ $vars.FEISHU_WEBHOOK_URL }}
{{ $vars.API_BASE_URL }}/v1/users
{{ $vars.ENV === "production" ? "prod-db" : "test-db" }}

Workflow Static Data

Persistent key-value storage scoped to a single workflow, read/written via the Code node's $getWorkflowStaticData() API. Used to remember state between runs — such as the last processed record ID:

// Read workflow static data
const staticData = $getWorkflowStaticData('global');
const lastProcessedId = staticData.lastId || '0';

// Update static data after processing
staticData.lastId = items[items.length - 1].json.id;
staticData.lastRunAt = new Date().toISOString();

return items;

Pro tip: Workflow static data is the key to implementing incremental sync — record the last synced timestamp or max ID, and on the next run only fetch new records rather than re-processing everything from scratch.

Putting It All Together

Understanding how these six concepts relate to each other gives you the complete mental model of how n8n works:

1. A Workflow is authorized by Credentials and waits for a Trigger Node to fire
2. The trigger produces the first batch of items (JSON array) that flow into the processing chain
3. Each node reads upstream items via Expressions, processes them, and outputs new items
4. Global Variables and Workflow Static Data serve as shared storage that persists across execution cycles
5. Each run generates an Execution Record capturing a complete data snapshot for debugging