Sub-workflow: pull shared logic into its own workflow

Why learn this

You have worked through Chapter 7 and know the three node families, Chapter 15 and can use IF/Switch, Chapter 17 and have an Error workflow in place, and Chapter 18 and can shape your data cleanly. You have more and more workflows, and they look more and more alike.

Then one day you open your own n8n home page and notice:

• Those four steps for "send a Slack notification" (IF on severity → Set the title → Slack sends the message → log to Sheets) are copy-pasted into five workflows
• Your boss suddenly says every notification from now on has to carry the line "please reply within 24 hours" — that is five places to edit
• The Slack channel changes from #alerts to #ops-alerts — five places again
• One day you forget one of them, a colleague never gets the notification, and you carry the blame

That is where copy-paste development always ends up. The fix: pull those four steps out into a small standalone workflow called a sub-workflow, and have the other workflows call it with an Execute Workflow node. From then on, changing the shared logic means changing that one sub-workflow, and every caller picks up the new version automatically.

What a sub-workflow is: two roles

A sub-workflow is not a special node type, and it needs no add-on. It is an ordinary workflow, just one designed to be called by others. The whole mechanism rests on two nodes playing two roles:

The whole mechanism looks like a function call in a programming language:

• The caller passes "arguments" (items) to the sub-workflow
• The sub-workflow takes those arguments and runs
• When it finishes, the sub-workflow hands the "return value" (the last node's items) back to the caller
• The caller treats that return value as the Execute Workflow node's output and carries on downstream

When to split out a sub-workflow, and when not to

Not every piece of logic is worth splitting out. Split too eagerly and your workspace fills with fragment workflows, which makes it harder to manage, not easier. Use this table to decide:

Hands-on: build a shared "send a Slack alert" sub-workflow

Walk through one concrete case. The logic to split out: "take an event, decide the channel and the color from its severity (error/warn/info), and send it to Slack." After that, any workflow that needs to notify calls this one.

1. Create a new workflow and name it [Sub] Slack Alert

   From the home page, Workflows → + Create workflow. Click the workflow name in the top right and change it to [Sub] Slack Alert. The [Sub] prefix is a convention (the naming section below covers it) that tells you at a glance this workflow is there to be called and never runs on its own.

2. Pick Execute Workflow Trigger as the trigger node

   On the canvas press Tab or click + to open the nodes panel, search for Execute Workflow Trigger (in the trigger family) and drag it in. This node's role is "when somebody calls me, I start here". Without it, another workflow's Execute Workflow node finds no entry point.

3. Set Input Data Mode to Define using JSON example

   Open the Execute Sub-workflow Trigger node and find the Input data mode dropdown. There are three official options: Define using fields below (type in each field name and type by hand), Define using JSON example (paste a sample JSON and n8n infers the schema for you) and Accept all data (no validation, whatever arrives is taken). Choose Define using JSON example here and paste:

   {
     "severity": "error",
     "message": "Database connection failed",
     "source": "backup-daily"
   }

   The benefit: the caller sees this schema hint in its own Execute Sub-workflow node and can assemble the data to match. That saves the back-and-forth over "what am I supposed to send you". A team that wants the interface contract written down first picks Define using fields below; a team that wants to take anything and sort it out later picks Accept all data.

4. Add an IF node to test severity

   Wire in an IF node with the condition {{ $json.severity }} equals error. The true branch goes to "post in the #ops-error channel with a red icon"; the false branch gets another IF for warn / info, or you can split three ways with a Switch node directly (Chapter 15 taught that Switch is designed for exactly this).

5. Slack nodes: the channel follows the severity

   Give each branch its own Slack → Message → Send node: the error branch's Channel is #ops-error, warn takes #ops-warn, and info takes #ops-info. Build the Text field from one shared expression: [{{ $json.severity | upper }}] {{ $json.source }}: {{ $json.message }}. All three channels then get the same-looking message, and you maintain it in one place.

6. Finish: let the workflow end on its own (no Respond to Webhook)

   Let each of the three Slack nodes be the end of its branch. When a sub-workflow finishes, the last node's items are sent back to the caller as the return value automatically — you do not add a Respond to Webhook (that one is for the Webhook node, not for sub-workflows). If you want to return a structure of your own, put a Set / Edit Fields node at the end and build it there (for example { "notified": true, "channel": "#ops-error" }).

7. Save (Ctrl+S) and copy the workflow ID

   After saving, look at the browser address bar: it reads something like https://n8n.woowtech.io/workflow/abc123XYZ — that last segment is the workflow ID. If the caller's Execute Workflow dropdown cannot find the workflow later, you can paste that ID straight in. Note: a sub-workflow does not need its Active toggle switched on, because it does not run from a trigger of its own — it waits to be called.

8. Test it once with the "Execute step" button on the Execute Workflow Trigger node

   Click Execute step in the top right of the Execute Workflow Trigger node and it does a trial run using the data you just pasted into the JSON example as its input. Of the three Slack nodes, only the error branch should fire (the example's severity is error). A Slack message actually arriving means the sub-workflow itself is sound.

Hands-on: call that sub-workflow from another workflow

The sub-workflow is built. Now open an existing workflow — "back up the database daily", say — delete the four Slack notification nodes you had stuffed inside it, and replace them with a single Execute Workflow node that calls the sub-workflow.

1. Open the workflow you are reworking

   Say you have a workflow that backs up the database in the small hours: Schedule Trigger → run the backup → IF on the exit code → a Slack message each for success and failure. Take that "send to Slack" stretch apart now.

2. Delete the old Slack nodes and drag in Execute Workflow

   Delete your own IF/Set/Slack nodes entirely. Search the nodes panel for Execute Workflow (the action one — do not mix it up with the trigger version) and wire it in after the IF node.

3. Set Source to Database and pick [Sub] Slack Alert in the Workflow dropdown

   Open the node. Source has four modes: Database (pick from the workflows already in the workspace, the usual choice), Local File (read a JSON file from the machine), Parameter (paste the whole workflow JSON into the node) and URL (point at a workflow URL). Keep the default Database and find [Sub] Slack Alert in the dropdown; if it is not there, switch to another mode and point at it by hand.

4. Check Wait for Sub-workflow Completion

   This toggle decides whether you wait for the sub-workflow to finish and hand back a return value before carrying on. On = wait; off = carry on as soon as the call goes out (fire-and-forget, which suits a pure notification where you do not care about the result). If you want to keep working with the data the sub-workflow returns, it has to be on. The official docs do not state the default; in practice a newly created Execute Sub-workflow node has it on, so check it yourself if you want to be sure.

5. Set Mode to Run once with all items

   Mode has two options: Run once with all items (hand every upstream item to the sub-workflow at once, and the sub-workflow runs once) or Run once for each item (each item triggers the sub-workflow separately, so it runs N times). For a one-at-a-time case like a notification, Run once with all items is fine.

6. Set the items you pass: use Workflow Inputs, or reshape with a Set node first

   If the sub-workflow defined a schema on its trigger (Define using fields below or Define using JSON example), the Execute Sub-workflow node automatically shows a Workflow Inputs table where you fill in an expression per field, plus an Attempt to convert types toggle that handles type conversion for you. If the sub-workflow is on Accept all data, that block does not appear and the upstream items go in untouched. To change the structure substantially, add a Set / Edit Fields node first, reshape to { severity, message, source }, and wire it in:

   severity: error
   message: {{ $json.error_message }}
   source: backup-daily

   Save, then run it once by hand with Execute Workflow to verify: the sub-workflow wakes up, Slack should get the message, and the Execute Workflow node on the caller's side shows the items that came back.

Two ways to pass parameters

How does the Execute Workflow node decide what to hand the sub-workflow? Two main modes, your choice:

Sub-workflow limits and things to watch

Splitting logic out feels good, but a few practical limits are worth keeping in mind, or you will trip over them six months from now:

Naming conventions: tell them apart at a glance

After a while a workspace holds dozens or hundreds of workflows, half of them parent workflows and half of them called by others. All mixed together, you cannot find anything. Sorting them by prefix is the simplest thing that works:

The workflow list page supports search, so typing [Sub] brings up every sub-workflow at once, which makes both editing and taking stock easy. WoowTech's own team has used this convention for a long time, and a new colleague gets it in a second.

Worked example: a family of utility sub-workflows

Once the sub-workflow idea has landed, you can build your team a shared toolbox. Here are four sub-workflows plenty of companies actually run, for reference:

With those four built, all your workflows get much cleaner:

• Need to notify? Do not assemble Slack yourself — call [Sub] Slack Alert
• Need a log? Do not assemble Sheets yourself — call [Sub] Log Execution
• Need to show a time to a person? Call [Sub] Format Local Date and the whole company shows one format
• Need to look up a colleague? Call [Sub] Get Employee Info, and when the internal API changes URL you edit only this one

Later the HR API address changes, the Slack channel is renamed, the timezone format is adjusted — you edit only the matching sub-workflow, and every workflow in the company picks up the new version automatically. That is what sub-workflows are really worth.

Common pitfalls and fixes

FAQ