Document a Salesforce Flow so another engineer can challenge it.
A screenshot can show a route through Flow Builder. It cannot explain which record changes enter that route, what happens on a second update, or which failures leave work unfinished. Those are the questions your documentation needs to answer.
8 min readBy aprity editorial · Updated
Write an execution contract: source version, start event, entry conditions, branch decisions, state changes and failure boundaries. Then challenge the explanation with inputs that take different routes.
The worked example below is an invented Opportunity-to-billing design. Its acceptance cases are review proposals, not Salesforce test results or an aprity customer implementation.
First establish which Flow you are describing
Record the Flow API name, type, environment, retrieval time and the version actually active in that environment. Keep the source snapshot beside the explanation. A repository file and a screenshot from another sandbox can both look credible while describing different behaviour. Resolve that mismatch before documenting a release.
For a record-triggered Flow, capture the Start configuration separately from downstream decisions. Object, create/update/delete event, before-save versus after-save timing, entry criteria and the update-entry setting are part of the contract. The phrase ‘when an Opportunity is won’ leaves several of these choices unspecified.
Salesforce's order-of-execution reference explains where record automation runs in a transaction. Use it to identify other automation that can affect the values being inspected. Do not infer the behaviour of the whole object from one Flow canvas. Record the neighbouring automation you inspected and anything still outside the review.
Work through a concrete execution contract
Assume an illustrative after-save Flow named Opportunity_Request_Billing. These are design assumptions for the example; verify the corresponding settings in your own source.
| Contract item | Example value | Question a reviewer must resolve |
|---|---|---|
| Entry | Opportunity updated; StageName equals Closed Won; only when updated to meet entry conditions | Does creation directly at Closed Won need a separate route? |
| Decision | Amount is positive and Billing_Request_Id__c is blank | What happens when the amount becomes positive after the first qualifying save? |
| Effect | Create a Billing_Request__c record with status Pending | Can another automation or integration create the same request? |
| Downstream boundary | A separate integration reads pending requests | Who proves that a request was accepted by the billing system? |
| Unknown | No retry or deduplication implementation supplied | Who owns this gap before anyone promises reliable invoice creation? |
The missed branch: a second update may not re-enter
Suppose the Opportunity first moves to Closed Won with Amount equal to zero. It meets the example's Start condition, but the downstream positive-amount decision rejects the billing route. Later, a user corrects Amount to 100 while StageName stays Closed Won. With the specified ‘only when updated to meet’ setting, that correction does not create a new transition into the Start criteria. The request may still be missing.
This is a design question, not a reason to silently change the Flow while documenting it. Options include moving eligibility into the entry criteria, deliberately handling later eligible updates, or defining a separate recovery route. Each changes behaviour. Describe the current route first, then record the proposed change and the owner's decision.
If a validation rule prevents the first zero-amount save, the scenario's starting state may be impossible through that path. That is why a Flow-only explanation and an org-level conclusion are different deliverables. Add the relevant rule to the review scope rather than assuming either outcome.
Use a branch table that exposes the difference
Expected outcomes under the isolated assumptions above. These cases have not been executed in a Salesforce org.
| Change | Expected Flow route | Evidence needed before sign-off |
|---|---|---|
| Prospecting → Closed Won, Amount 100, no request ID | Enter and take the request route | Created request and its link to the Opportunity |
| Prospecting → Closed Won, Amount 0 | Enter; reject the positive-amount branch | Decision outcome; any competing validation error |
| Already Closed Won, Amount 0 → 100 | No new transition into Start criteria | Start configuration and observed execution behaviour |
| Closed Won → Prospecting → Closed Won | Can qualify again; existing-request branch matters | Duplicate prevention beyond the blank-field check |
| Create directly as Closed Won | Outside this update-only example | Separate create automation or an explicit coverage gap |
Document transaction boundaries before drawing arrows
Separate a local record write, an asynchronous handoff and an external acknowledgement in the description. ‘Creates the invoice’ is an overclaim if the source only creates a pending request. The contract should say what the Salesforce transaction establishes and where another process takes over.
For each data operation or action, inspect its fault route where supported and the surrounding transaction behaviour. Record whether the route reports an error, records recoverable work, or leaves the operator without a useful status. A fault connector is evidence of a configured route; it does not by itself prove rollback behaviour, successful recovery or an effective alert.
For invoked Apex or a subflow, record the input mapping and follow the implementation far enough to support the claimed effect. If the implementation is unavailable, stop at the invocation: name the supplied inputs and mark the downstream behaviour unverified.
Review the explanation with deliberately awkward cases
Change one predicate at a time
Keep the other inputs fixed and cross the Amount boundary: negative, zero, positive and blank. Compare transition into the qualifying state with an update inside that state. Each case should explain which decision changes.
Challenge volume and repeated delivery
Ask how the design behaves for an import, repeated updates and a duplicated downstream request. Document the proposed test population and idempotency contract. A single successful save cannot establish bulk or retry safety.
Walk the failure with the support team
Give an operator a pending request with no acknowledgement. They should find the owner, diagnostic evidence and authorised recovery procedure without asking the author to interpret the diagram.
Publish the review boundary
State which source revision was reviewed, which cases were only derived from source and which were executed. Attach actual results separately and revisit the explanation when Start settings, branches or called components change.
Key terms in this guide: Before-save vs after-save flow, Salesforce order of execution, Record-triggered flow.
Use generated explanations as a review starting point
aprity turns supported Salesforce metadata into a documentation portal. Use that source-oriented view to locate automation and inspect explanations, then apply the branch review above. Business intent, external outcomes and executed acceptance remain evidence your team must supply.
- Compare explanations with the retrieved source.
- Keep unverified downstream effects visible.
- Review the affected contract after a change.
Frequently asked questions
Is a Flow screenshot enough documentation?
It helps orientation, but the contract also needs the active version, Start settings, branch conditions, inputs, effects and failure boundaries. A screenshot alone rarely establishes all of these.
Should Flow documentation describe the intended or current behaviour?
Keep them separate. Describe the observed configuration, record the owner's intended outcome, and track discrepancies as decisions or defects. Otherwise documentation can conceal the very issue it should expose.
Related guides
A Salesforce handover kit the receiving team can actually use.
A folder of diagrams can be delivered while the incoming team still cannot explain a failed order. Treat the handover as a transfer of operating responsibility, with a practical exercise that shows what has—and has not—been transferred.
Read the guide AI evaluationEvaluate AI Salesforce documentation beyond fluent explanations.
An explanation can be readable, well formatted and wrong about the condition that matters. Evaluate whether a reviewer can rely on its claims, find its omissions and correct it without reconstructing the whole component.
Read the guideSee it on your own org, not on a slide.
A free 14-day trial documents your org from a computed dependency graph — read-only, no credit card, and you review the output before deciding anything.