n8n nodes receive items, apply an operation, and emit items along connections. Reliable workflows make the data contract at each boundary visible. A green node does not prove the business state is correct.

// concept

Model Items Explicitly

Use a canonical envelope:

// json8 lines

{
  "event_id": "evt-sample-01",
  "event_type": "lead.submitted",
  "occurred_at": "2026-07-19T10:00:00Z",
  "tenant_ref": "sample-shop",
  "payload": { "city": "Karachi", "service": "catalog setup" },
  "schema_version": "1"
}

At each node record expected fields, output fields, cardinality, empty-input behavior, and error behavior. Avoid mutating a broad untyped object throughout the workflow. Select and rename the fields each stage owns.

// concept

Understand Branching and Merging

An IF/Switch branch creates separate paths. A Merge node’s result depends on mode and item linking. Test zero, one, and many items on every branch. Do not assume branch order or pair records by position if an ID join is required.

For batch operations, preserve event_id or business reference. If one input produces several outputs, add a stable child key. If several inputs aggregate, record the source IDs.

// worked_example

Worked Example

A sample order list contains three items. The workflow validates each, branches supported and unsupported cities, and produces two accepted drafts plus one review case. A merge by stable order_ref combines approved catalog data; it does not join “first with first.”

The output includes counts and source references. Empty input yields an explicit NO_ITEMS result rather than silently succeeding and triggering a downstream message.

Save this execution as a regression fixture so later node or n8n upgrades must preserve the same accepted, review, and empty-item behavior.

// failure_cases

Failure Cases to Diagnose

6 cases to diagnose

Position-based merge after filtering
join by stable ID.
Node drops identifiers
carry trace and business refs.
Empty branch treated as success
define zero-item behavior.
Large binary copied through every node
store/reference appropriately.
Expression points to a different branch item
inspect linking and execution data.
Schema changes silently
version and validate boundaries.

// pakistan_angle

Pakistan Angle

Normalize Pakistani phone numbers only after user confirmation and keep the original authorized source. Do not use phone, city, name, or language as a proxy for sensitive traits or customer value.

For orders, preserve exact PKR fields and source. A formatted PKR 2,490 string is for display; arithmetic should use a documented exact representation. Never merge a payment event to an order by customer name.

// hands_on

Hands-On Exercise

5 steps

Define one canonical event envelope.
Annotate each node’s input/output/cardinality.
Test zero/one/many items.
branch and merge using stable IDs.
export three execution fixtures.

// completion_rubric

Completion Rubric

6 checks — tick as you verify

0/6

// sources

Sources

3 official sources — check every claim yourself

// check_yourself

Check yourself

4 questions · answers and options are taken word-for-word from this course

0/4

1 / 4 · diagnose
Your work shows this failure mode: “Empty branch treated as success.” What does the lesson tell you to do about it?