How to document a Salesforce Flow
Flow Builder shows you the canvas. It does not tell you what the Flow changes, what it depends on, or what breaks when you edit it — and those are the three things anyone reading the documentation actually needs.
8 min readA screenshot of the canvas is not documentation. To document a Flow you need four things the builder never puts in one place: what starts it and under which entry conditions, every record it writes, everything outside itself it calls or depends on, and where it sits in the order of execution relative to the other automation on the same object.
All four are recoverable from the Flow's metadata. The work is reading .flow-meta.xml, resolving what each element points at, and writing the result in the language the business actually uses.
What “documented” has to mean for a Flow
A Flow is a program. Documenting it means the same thing documenting any program means: someone who has never opened it should be able to predict what it does, and someone about to change it should be able to predict what they will break.
In practice that comes down to four questions. What triggers it — record-triggered before or after save, schedule-triggered, platform event, screen Flow launched from where? Under what entry conditions, and does it re-enter on update? What does it write — which objects, which fields, under which branch of which decision? And what does it reach outside itself: subflows, Apex invocables, email alerts, outbound callouts, custom metadata it reads for configuration?
The fourth question is the one most documentation skips: order of execution. A record-triggered Flow does not run alone. It shares the save order with validation rules, other Flows on the same object, Apex triggers, roll-up summaries and duplicate rules. A Flow that is correct in isolation and wrong in sequence is a Flow that will be blamed for a bug it did not cause.
Reconstructing it from the metadata
This is the reliable way to do it by hand. It is also the part that does not survive contact with a second Flow, a third, and a release cycle.
Retrieve the Flow metadata
Pull the Flow definitions out of the org with the Salesforce CLI rather than reading the canvas —
sf project retrieve start --metadata Flowgives you the.flow-meta.xmlfiles. The XML is the source of truth the builder renders; it contains elements the canvas summarises or hides behind a panel.Map the elements to their types
Walk the XML and classify each element: record lookups and their filters, record creates and updates with the fields they set, decisions and every outcome branch, assignments, loops, action calls, and subflow references. The element names are the Flow's own vocabulary — keep them, so a reader can move between your document and the builder without translating.
Resolve what each element points at
An element that sets a field is only half a fact. Follow the field to its definition: is it a formula that depends on other fields, does a validation rule govern it, is it required on a page layout, does an Apex trigger touch it after the Flow does? A Flow's real footprint is the closure of these references, not the list of elements.
Place it in the order of execution
List every other automation on the same object and establish the sequence: before-save Flows, then triggers, then after-save Flows, then the rest of the save order. Record the Flow's trigger order value if it has one. Without this the document explains a Flow that never runs in the conditions you described.
Write it in business language, then keep the trail
Translate the mechanism into what it means — “when a contract is signed, the renewal date is set twelve months out unless the account is on a legacy plan”. Then keep a pointer from every sentence back to the element or field it came from, so the next reader can verify a claim instead of trusting it.
The four traps that make Flow documentation wrong within a quarter
It documents a version, not the Flow
Flows are versioned, and only one version is active. Documentation written against version 4 stays on the shelf while version 7 runs in production. Unless the document names the version it describes, nobody can tell whether it is stale.
The Description fields are empty
Salesforce gives every Flow and every element a Description field. It is the one place documentation would travel with the metadata — and it is almost always blank, because writing it is not required to save.
Subflows hide the logic
A tidy parent Flow that calls three subflows looks simple and is not. Documentation that stops at the subflow boundary describes an outline, and the behaviour a reader is looking for is usually one level down.
Screenshots age silently
A canvas image is wrong the moment someone drags an element, and nothing in the org signals that the picture no longer matches. Text that names elements can at least be checked against the metadata; an image cannot.
Where aprity fits
aprity reads the org's metadata through a read-only connection and computes the dependency graph deterministically — the same question always returns the same answer, because no model is involved in producing it. The LLM comes in afterwards, to narrate what the graph already established.
For a Flow that means the walk-through is generated rather than written: each screen and each branch in sequence, in business language, with a confidence score and a link back to the metadata the claim came from. It is regenerated on every scan, so the version drift above stops being a class of problem.
- Every screen Flow documented step by step, branch by branch
- The real execution graph — node-level read, write and call
- Scan-to-scan diff of what changed in business terms
- Read-only access; raw metadata purged after every scan
How to document a Salesforce Flow — FAQ
Can Salesforce generate Flow documentation on its own?
Not as documentation. Flow Builder renders the canvas and exposes a Description field on the Flow and on each element, and the metadata API will give you the underlying XML — but nothing in the platform assembles those into a readable account of what the Flow does, what it writes, and what depends on it. That assembly is the work.
Is the Flow's Description field enough?
It is the best place to put a one-line intent, and filling it in is worth the discipline. It is not enough on its own: it is free text with no link to the elements, nothing validates it against what the Flow actually does, and it goes stale as quietly as any other comment.
How do I document the order of execution between several Flows?
Record-triggered Flows on the same object and in the same context run in the order set by their trigger order value, and if that is unset the order is not guaranteed. Document the value explicitly for every Flow on a busy object, alongside the triggers and validation rules that share the save order — a Flow described without its neighbours is described incorrectly.
How often does Flow documentation need refreshing?
As often as the org changes, which is why hand-written Flow documentation loses. The practical answer is to generate it from the metadata on a schedule so the document and the org cannot drift, and to keep a diff between two points in time so a reviewer can see what moved rather than re-reading everything.
Related guides
How to find everywhere a Salesforce field is used
Salesforce will tell you most of the places a field is referenced. The dangerous part of the answer is the remainder — the references no static check can see, which is exactly where deletions go wrong.
Read the guide GuidePreparing a Salesforce org for an ISO 27001 audit
The certificate is for your information security management system, not for your org. What the auditor wants from Salesforce is narrower and more awkward: evidence that access, change and logging work the way your policy says they do.
Read the guideSee it on your own org, not on a slide.
A free 14-day evaluation documents your org from a computed dependency graph — read-only, no credit card, and you review the output before deciding anything.