Module 1: Why Version Your Workflows

8. Project: audit and export a workflow

Next →

Description

By the end of this lesson you will have your first real deliverable for the guide: a workflow exported as JSON, read field by field, accompanied by a portability risk note documenting every point that would break when moving that workflow to another instance. You aren't going to learn a new concept; you're going to put your hands on everything you learned in the previous seven lessons and produce an artifact that serves as the foundation for the rest of the guide.

This matters because it's the difference between having read about versioning and having started doing it. The seven lessons gave you the why (1, 2), the problem (3, 4, 5), the model (6), and the economics (7). None of that sticks until you export a real workflow, open it, and point your own finger at "here's the credential ID that's going to break." And the risk note you're going to write isn't a practice exercise you throw away: it's the first stone of the portfolio artifact from lesson 2, and the document Modules 3 and 4 build their solutions on.

Connection to the module: this project assembles the seven lessons. The Download is from lesson 3; reading the JSON with judgment is lesson 4; identifying what breaks is lesson 5; understanding why documenting it matters is lesson 6 (the repo as source of truth needs the why written down); and knowing all this is free is lesson 7. If anything below feels unfamiliar, that's the lesson number worth going back to. And looking ahead: the JSON you export here is what you're going to version with Git in Module 2, and the risk note is what you're going to resolve, point by point, in Modules 3 and 4.

What you're going to deliver

Two files, which together are your first system-owner deliverable:

  1. The exported JSON of a real workflow —Cumbre's order-triage if you've built it, or any workflow of yours using at least one credential; ideally one with a webhook and a call to an external API, so all four fragile points show up.

  2. The portability risk note: a short document, in plain text or Markdown, that for the chosen workflow lists every field that would break when imported into another instance, classified by fragile point, with what it would take for it not to break. It's the direct application of lesson 5 to your concrete workflow.

module-1-deliverable/
  ├── order-triage.json          ← the exported workflow (lesson 3)
  └── PORTABILITY-RISKS.md        ← the risk note (lesson 5)

On time: exporting and reading the JSON takes about twenty minutes; writing the risk note carefully, another twenty. It's a short project on purpose: its value isn't in the length, it's in you actually going through the motion of auditing a workflow before moving it, which is the motion you were missing.

A note on file names: they go in English, following the whole ecosystem's convention. order-triage.json, PORTABILITY-RISKS.md, module-1-deliverable/ —well, that last one is your local working folder, name it whatever you want; the ones that matter, the ones that will live in the repo, go in English.

It's worth looking at this deliverable through lesson 2's lens: it's the first version, humble but real, of the portfolio artifact. An evaluator opening this folder would already see a move the builder doesn't make —auditing a workflow before moving it— and a capability most people don't have: anticipating in writing what breaks. It's not the complete repository yet; it's its first stone. And since every module adds a piece on top of the previous one, starting well here —with a workflow that actually matters to you and a specific note— saves you from redoing the work later.

Phase 0 — Choose and prepare the workflow

You need a workflow to audit. You have three paths, in order of preference.

Path A — Cumbre's order-triage. If you've been following the guide and built (or are about to build) the case-study workflow —receives orders by webhook, queries the CRM over HTTP, classifies with an AI Agent node— that's the ideal one, because it has all four fragile points: two credentials (CRM and AI provider), a webhook, and values that change per environment. If you haven't built it yet, you can build a minimal version: a Webhook node, an HTTP Request node to any API requiring a credential, and an AI Agent node with a model provider's credential. It doesn't have to do anything useful yet; it just has to exist and have those pieces.

Path B — a real workflow of yours. If you already have workflows on your instance, pick the one you most care about being portable: ideally one with a webhook and at least one credential. It's even better than the case study, because the analysis is done on something you actually want to protect.

Path C — a minimal practice workflow. If you have neither, build in five minutes a workflow with a Manual Trigger, an HTTP Request with any authentication credential (even to a public API requiring a key), and save it. With just one credential you can already practice the most important fragile point.

Step 0.1. Open the chosen workflow in the n8n editor. Make sure you save it before exporting —remember from lesson 3 that export pulls what's saved, not the last thing you touched without saving.

What to expect: the workflow open, saved, with at least one node using credentials. If your workflow doesn't use any credential, fragile point 1 —the most important one— won't show up, so it's worth adding even just one node with authentication so the exercise has substance.

Phase 1 — Export the workflow

Step 1.1. With the workflow open and saved, open the three-dot menu (⋯) at the top right and choose Download. (Check the exact label on your version; if the menu is somewhere else or the option is named differently, look for it: it's the one that downloads the workflow as a .json file.)

What to expect: your browser downloads a file with a .json extension. The default name is usually the workflow's name. Save it to your deliverable's working folder and, if you want, rename it to order-triage.json (or the English name matching your workflow).

Step 1.2 (optional but recommended). Also open the workflow with the copy shortcut: select all the nodes (Ctrl+A) and copy (Ctrl+C). Paste the result into a text editor and compare it with the file you downloaded. What to expect: the content is essentially the same JSON. This step isn't for the deliverable; it's for you to confirm with your own eyes, once more, that the two export methods (lesson 3) produce the same thing.

Micro-check: open the .json file in a text editor (any one works: your usual code editor, or even Notepad). If you see a big block of text starting with { and containing the words nodes and connections, you exported correctly. If the file is empty or doesn't look like JSON, something failed in the download; try Download again.

Phase 2 — Read the JSON with lesson 4's eyes

Now for the part that separates auditing from just looking. You're going to walk through the file with lesson 4's structure in hand, locating each part. You don't need to understand every character; you need to be able to point to where each thing is.

Step 2.1 — The top-level sections. In your file, locate and note which area of the file has: name (the workflow's name), nodes (the node list, starts with [), connections (the object mentioning node names), settings, active, and if they exist, pinData, meta, versionId, tags.

What to expect: you'll find nodes and connections as the biggest sections, and the others shorter. If your n8n version names some field differently from how lesson 4 describes it, note it down: half of lesson 4's point was confirming that exact names can vary by version.

Step 2.2 — A node from the inside. Pick your workflow's most interesting node —the one using credentials— and locate, inside its object: name, type, typeVersion, parameters, position, id, and credentials (if it has one).

Step 2.3 — The credentials field. This is the one that matters most. If your node uses credentials, locate its credentials section and note exactly what you see: the credential type, the id (a number or short string), and the name (the readable name). What to expect: you'll see the id and the name, but not the secret itself —not the password, not the API key. Confirming that with your own eyes closes lesson 4's central idea: the JSON stores a reference, not the secret.

Step 2.4 — Classify five fields. Take any five fields from your file and classify them as stable or volatile per lesson 4. For example: parameters (stable), position (volatile), node name (stable), node id (volatile), versionId (volatile). What to expect: you should be able to justify each classification in one sentence —"position is volatile because it changes just by moving the node, without changing behavior."

Phase 3 — Hunt the fragile points with lesson 5

With the file already mapped, now you apply lesson 5's list: you walk through the four fragile points and note which ones show up in your workflow and where.

Step 3.1 — Fragile point 1: credential IDs. Search the file for every credentials section. For each one, note: the type, the id, and the name. Each one of these is a point that would break on import into another instance, because that id is per instance. What to expect: if your workflow has two credentials (like order-triage, with the CRM and the AI Agent), you note two. If it has one, you note one. If it has zero, your workflow doesn't have this risk —but then it's worth adding a node with a credential so the exercise has the most important point.

Step 3.2 — Fragile point 2: node IDs. Locate the nodes' ids (those long barcode-like strings). Note that they exist and could get regenerated on import. Remember from lesson 5 that this usually doesn't break the flow —connections use names— but it clutters the history. What to expect: as many ids as your workflow has nodes.

Step 3.3 — Fragile point 3: webhooks. Check whether any node is a webhook type (for example n8n-nodes-base.webhook). If there is one, locate its path and its webhookId, and note that the webhook's URL would change when moving the workflow, breaking any external system calling it. What to expect: if your workflow starts with a webhook, this is one of the most important risks to note, because it's the only one that breaks things outside n8n and gives no signal inside. If you use a Manual Trigger instead (path C), note that: you don't have this risk, and that's also information.

Step 3.4 — Fragile point 4: environment values and variables. Walk through your nodes' parameters looking for fixed values that should change per environment: service URLs (does it point to production?), account identifiers, thresholds, anything hand-written that should be different in dev than in prod. Note each one. What to expect: at least one URL or value that, if you imported the workflow into a test environment, would still point to the real thing. This is the silent point: it doesn't break visibly, but it can make a "test" touch real data.

Worked example: a complete audit of order-triage

Before you write your note, let's walk through a complete audit pass on order-triage's skeleton from lesson 4, so you have a model to follow. I'm going to read the file out loud, the way you would, noting what matters as it comes up.

I start from the top. "name": "order-triage" —good, it's the workflow I want. I go into nodes and see three objects. The first is the webhook.

Node "Order received (Webhook)". Its type is n8n-nodes-base.webhook. Fragile point 3 alarm: there's a webhook. I note: path is "order-triage," it has a webhookId. This webhook's URL is going to change when moving the workflow, and Cumbre's store sends orders here. This is what breaks outside n8n with no warning. I flag it with a star, because it's the one nobody remembers.

The second node is the CRM call.

Node "Get customer from CRM." type n8n-nodes-base.httpRequest. I look at its parameters: the url is https://crm.example.com/api/customers/..., hand-written. Fragile point 4: this value points to the same CRM regardless of environment; if I import this into dev, it's going to call the real CRM. I note it. And I look at its credentials: type httpHeaderAuth, id "27," name "Cumbre CRM - Header Auth." Fragile point 1: that id "27" is per instance. I note it as credential risk number one.

The third node is the agent.

Node "Classify order (AI Agent)." type @n8n/n8n-nodes-langchain.agent. Its credentials: type openAiApi, id "14," name "Cumbre OpenAI - Dev." Fragile point 1 again: second credential that breaks. And I notice the "Dev" suffix in the name —a hint that in prod this should be a different credential, not the dev one. I note it: when promoting to production, make sure to use the production credential, not carry over the dev one.

I review the ids of the three nodes —11111111-..., 22222222-..., 33333333-.... Fragile point 2: they can get regenerated on import; they don't break the flow because connections uses names, but they clutter the diff. I note it as a minor risk, to normalize in Module 3.

I close with connections —the arrows go from the webhook to the CRM and from the CRM to the agent, all by name, so they survive the move— and with settings, active: false, etc.

What to expect from this pass: by the end I have, on paper, six notes —one webhook, two credentials, three node IDs, one hard-coded URL— each with its exact name and location. That's exactly what the risk note is going to formalize. Notice the method: I read the file top to bottom, and for every node I ask myself the four fragile points in order. I don't search randomly; I walk through it with a list. That's the difference between auditing and looking.

Phase 4 — Write the portability risk note

Now you turn your notes into the deliverable document. The risk note has a simple structure and a clear purpose: that anyone —including you in three months— can read, before moving this workflow, exactly what needs checking so it doesn't break silently.

Step 4.1. Create a PORTABILITY-RISKS.md file with this structure. Write the prose in English (or Spanish, if you're producing this on the Spanish track) and the identifiers (node names, credential names, fields) in English, as throughout the whole repo:

# Portability risks — order-triage

What to check BEFORE importing this workflow into another instance.
Each point is something that breaks silently if not controlled.

## 1. Credentials (breaks on execution)
- Node "Get customer from CRM": credential `httpHeaderAuth`, id 27,
  name "Cumbre CRM - Header Auth".
  → Recreate on the destination instance and reassign. Use the correct environment's.
- Node "Classify order (AI Agent)": credential `openAiApi`, id 14,
  name "Cumbre OpenAI - Dev".
  → Recreate and reassign. Watch out: in prod it must be the prod credential, not the dev one.

## 2. Node IDs (clutters the history)
- All three nodes have an id that can regenerate on import.
  → Does not break the flow (connections use names), but normalize
    for clean diffs (Module 3).

## 3. Webhook (breaks OUTSIDE n8n, with no warning)
- Node "Order received (Webhook)": path "order-triage".
  → The URL changes with the destination instance's domain.
    Update the external system (Cumbre's store) to call
    the new URL. NOBODY warns you if you forget.

## 4. Environment values (breaks silently / dangerous)
- Node "Get customer from CRM": url "https://crm.example.com/..."
  hand-written.
  → Points to the same CRM regardless of environment. In dev/staging
    it should point to the test CRM. Move the value to per-environment config (Module 4).

## Verification after importing
1. Open every node with credentials, confirm it is not red.
2. Reassign credentials for the correct environment.
3. Note the new webhook URL and rewire the external system.
4. Review fixed values that should change per environment.
5. End-to-end test with test data, not just a manual run.

Adapt the content to your workflow: if it has a single credential, your section 1 has one point; if it has no webhook, your section 3 says "not applicable: uses Manual Trigger" —which is valuable information, not a gap.

Step 4.2. Reread your note asking yourself: "if I hand this document to someone who's never seen the workflow, would they know what to check before moving it?" If the answer is yes, the note does its job. If any point is vague —"check the credentials" without saying which ones or where— make it precise. The difference between a useful note and a useless one is specificity: concrete names, concrete locations, concrete actions.

What to expect: a document one or two screens long, scannable, that a coworker can read in two minutes and use as a checklist. It's not an essay; it's a list of risks with their action. That format —concise, actionable, with the why implicit in the action— is the one you're going to use for Module 6's complete runbook.

Phase 5 — Verify the deliverable (and, if you can, prove it)

Step 5.1 — Deliverable checklist. Confirm you have:

  • The exported .json file, which opens and looks like valid JSON.
  • You located its main sections (nodes, connections, credentials if applicable) inside it.
  • The PORTABILITY-RISKS.md note with all four fragile points, each with concrete names and locations, and its action.
  • A post-import verification section in the note.

Step 5.2 — The real proof (optional, highly recommended). If you have a way to spin up a second n8n instance —another one on your machine, a clean one in Docker— do the test that closes the module: import your workflow there and watch what breaks. What to expect: you'll see the nodes with credentials flagged in red (point 1), you'll notice the webhook has a different URL (point 3), and you'll confirm with your own eyes that your risk note predicted exactly what happened. There's no better way to cement lesson 5 than watching your prediction come true. If you can't spin up a second instance right now, don't worry: in Module 4 you're going to set up real environments, and there'll be plenty of chances to prove it there.

Step 5.3 — Save it properly. This deliverable isn't disposable. The JSON is what you're going to version with Git in Module 2, and the risk note is what you're going to resolve, point by point, in Modules 3 and 4. Put it somewhere you won't lose —ideally, the folder you're going to initialize your cumbre-automations repository from in the next unit.

Common mistakes

Auditing the JSON "from memory" without opening the file (practical). What happens: someone writes the risk note based on what they remember about the workflow, without opening the exported JSON, and misses things —a second credential they forgot, a fixed value buried in a node. Why it happens: it feels faster, and you think you know your own workflow. How to spot it: if your note doesn't cite ids or concrete locations, you probably didn't open the file. How to fix it: the audit is done on the file, not on memory. The JSON always has more than you remember —n8n puts in IDs, metadata, default values you never saw in the editor. Opening the file is the whole point of the exercise.

Writing a vague risk note (practical). What happens: the note says things like "check credentials" and "check the webhook," with no names, no locations, no actions. When someone uses it three months from now, it doesn't help: they don't know which credentials or what to do. Why it happens: writing specifics costs more, and in the moment everything is fresh in your head, so the vagueness doesn't show. How to spot it: if a point in your note doesn't say the concrete name of what breaks and the concrete action to fix it, it's vague. How to fix it: every point carries a name (which node, which credential), a location (where in the JSON), and an action (what to do). Specificity is what turns a note into a tool; vagueness turns it into decoration.

Treating the project as disposable (conceptual). What happens: someone does the exercise "to check the box," with a toy workflow they don't care about, and throws away the result. They miss that this is the first brick of the portfolio artifact and the foundation for the following modules. Why it happens: it's the module 1 project, it feels introductory. How to spot it: if you chose a workflow you don't care about and don't plan to keep, you're treating it as disposable. How to fix it: choose a workflow you actually want to carry through to the end of the guide —order-triage or a real one of yours— because this JSON and this note are going to grow with you module by module until they become the final deliverable. Starting with something real saves you from redoing it later.

Forgetting to save the workflow before exporting (practical). What happens: someone touches the workflow in the editor, exports without saving, and the JSON doesn't include the last change, because export pulls what's saved (lesson 3). Then the risk note analyzes a state that isn't the current one. Why it happens: the editor doesn't always make it obvious there are unsaved changes. How to spot it: if the JSON is missing something you swear you changed, you didn't save. How to fix it: always save before exporting. It's step one of phase 1 for a reason; make it a reflex, because this same stumble is going to lurk every time you export for the rest of the guide.

Exercises

These exercises extend the project: they don't repeat what you already did, they go deeper.

Exercise 1 — Predict and verify. Before importing your workflow into a second instance (if you can), write a three-line prediction: what exactly do you expect to see broken when you open it on the other side. Then import it and compare your prediction with what happened.

See solution

A typical prediction for order-triage: "Both nodes with credentials (CRM and AI Agent) are going to show up red or with no credential selected. The webhook is going to have a different URL. The node flow is going to be complete and the connections intact, because they use names."

What the verification almost always confirms: exactly that. The credentials get flagged (n8n points them out for you), the webhook changes URL (nothing points it out), and the connections survive. If something surprises you —a behavior you didn't predict— that's the exercise's most valuable finding: it's a fragile point your mental model didn't capture yet, and now it does.

Why it works: predicting before verifying is what turns a passive observation into active learning. When your prediction holds, lesson 5 goes from "something you read" to "something you know." When it fails, you found your blind spot, which is even more useful.

Exercise 2 — Anonymize for sharing. Imagine you're about to upload your workflow's JSON to a public forum to ask for help. Review the file and note what you'd have to remove or change before sharing it, per the security warning from lessons 3 and 4.

See solution

What needs reviewing before sharing a JSON publicly:

  • The credential names. The IDs aren't secrets, but a name like "Cumbre CRM - Production - Main API Key" reveals information about your infrastructure. Anonymize them to something generic.
  • Authentication headers in HTTP nodes. If any HTTP Request node was created by importing a cURL command, it might carry a real token or key inside parameters (for example in an Authorization header). That's a real secret: remove it.
  • Internal URLs. Addresses of internal services (https://crm.internal.cumbre.local/...) reveal your architecture. Consider replacing them with example.com.
  • pinData. If you pinned test data, it might contain real information you captured during a run. Check it.

Why it works: this exercise trains the security reflex you're going to need throughout the guide. Sharing a JSON —on a forum, with a client, in a public repo— without reviewing it is one of the most common ways to leak information unintentionally. And along the way, it reinforces lesson 4's idea: the JSON stores (safe) references, but it can also drag along real secrets in specific spots (headers, pinData) that need watching.

Exercise 3 — Write the "why I'm versioning this." In three or four sentences, write the justification for why this specific workflow deserves to be versioned, addressed to someone who asked you "why all this fuss over one workflow?" Use what you know from lessons 1 through 3.

See solution

One possible justification for order-triage:

"This workflow processes the company's real orders: if it breaks, orders stop coming in, which is money. Versioning it gives me three things I don't have today: if a change breaks it, I go back to yesterday's version in a minute instead of guessing; if someone else touches it, we don't silently step on each other; and when I'm not around, it's written down why it's built this way, including what breaks if someone moves it —which is exactly what I documented in the risk note. It's not 'all this fuss over one workflow': it's that this workflow is a system the operation depends on, and systems you depend on get versioned."

Why it works: the justification connects the abstract value (history, rollback, collaboration) to the concrete cost of this workflow failing (orders stop coming in). That connection —from the general benefit to the specific risk— is what convinces a skeptical boss and what convinces you yourself when the work of versioning starts feeling tedious. If you were able to write it, you closed the module's argument: you know not just how to start versioning, but why it's worth it.

Summary and next step

In this project you produced your first system-owner deliverable: a workflow exported to JSON and a portability risk note documenting, with concrete names and locations, every field that would break when moving that workflow to another instance. You assembled the module's seven lessons: you exported with lesson 3's Download, you read the JSON with lesson 4's structure —locating nodes, connections, and above all the credentials field that stores a reference and not the secret— you hunted the four fragile points with lesson 5's list, and you wrote the note with the documentation discipline lesson 6's model demands. And you did it entirely in Community, for free, as lesson 7 said. If you could, you verified your prediction by importing the workflow into a second instance and watched your risks come true with your own eyes.

Before closing the module, confirm you can: export a workflow and open its JSON; locate its main sections and its credentials field; and write, for a given workflow, a specific and actionable risk note. If all three are there, you've mastered the module's output capability: explaining why export/import doesn't version, reading the JSON's structure, and identifying what breaks in a naive reimport.

What's next is to stop auditing and start versioning. You have the exported JSON and you know exactly what makes it fragile; Module 2 teaches you Git from zero —for someone who's never touched it— to turn that file into a workflow under real version control: with history, with the ability to read every change as a diff, with branches to work without fear, with a backup on GitHub, and with the ability to go back to a version that worked. The file you exported today is the seed of the cumbre-automations repository you're going to build in the next unit. Keep it safe; the next time you see it, it's going to be your history's first commit.

Resources

← Previous7. Source control: Community vs Enterprise, with honestyNext →1. Introduction: Git applied to workflows