Flow Best Practices
Rules for writing flows that read well, test well, and keep their context.
A flow can be written many ways that all run. These rules pick one way for each common situation, so flows read alike and are easy to test. Each rule has a short id in brackets. Dr. Octo and the MCP server's write-effective-integrations prompt teach the same ids, and scripts/check-flow-practices.mjs enforces the mechanical ones on every sample.
Use one multi-transform for a run of setters
Two or more set-variable or set-payload blocks in a row become one multi-transform. Its steps run in order and each one sees the result of the one before, so nothing is lost by merging them. One block is one step in logs and traces, and one address to mock.
# ✗ three blocks for one step
- type: set-variable
name: keep-id
settings: { name: orderId, value: body.id }
- type: set-variable
name: keep-total
settings: { name: total, value: body.qty * body.price }
- type: set-payload
name: build-response
settings:
value: '{"orderId": vars.orderId, "total": vars.total}'
# ✓ one block
- type: multi-transform
name: price-order
settings:
transforms:
- setVar: orderId
value: body.id
- setVar: total
value: body.qty * body.price
- setBody: '{"orderId": vars.orderId, "total": vars.total}'A set-payload that sets rawBody stays its own block, because setBody has no raw mode. Any other deliberate exception, such as a sample that shows setters on purpose, carries # practices: allow multi-transform on the line above the block.
Keep context with enrich around a destructive call
Most connector blocks put their result in the body, which replaces what was there. When later steps still need the old body, run the call inside an enrich. The scope gets a copy of the message, and only what you lift out with setVars or setBody comes back. Don't save the body in a variable and rebuild it afterwards.
# ✗ save the body, overwrite it, rebuild it
- type: set-variable
name: keep-event
settings: { name: event, value: body }
- type: odoo-search-read
name: find-reason
settings: { connector: odoo, model: '"crm.lost.reason"', domain: '[["name", "=ilike", body.reason]]' }
- type: set-payload
name: restore-event
settings: { value: vars.event }
# ✓ the event stays the body; only the ids come out
- type: enrich
name: find-reason
setVars:
reasonIds: body.map(r, r.id)
body:
process:
- type: odoo-search-read
name: search-reason
settings: { connector: odoo, model: '"crm.lost.reason"', domain: '[["name", "=ilike", body.reason]]', fields: [id] }Prefer resultVar for a single call
When the destructive step is one connector operation that has a resultVar setting, set it instead of wrapping the block in an enrich. The result lands in vars.<name> and the body is left alone. Use enrich when the scope has several steps, when you want to derive something from the result rather than keep it whole, or when the block has no resultVar. flow-ref, rest and sql don't have one.
- type: odoo-search-read
name: find-contact
settings:
connector: odoo
model: '"res.partner"'
domain: '[["email", "=ilike", body.email]]'
fields: [id]
resultVar: contacts # body is still the requestSplit long flows into subflows
A flow that grows past roughly eight to ten steps, or that contains a piece another flow could use, gets split. Move the piece into a sourceless flow (a flow with no source) and call it with flow-ref. Each flow then gets its own suite, so the piece is tested with a direct input instead of only through everything around it.
A two-way flow-ref replaces the caller's body with the subflow's result and merges the subflow's vars back. When the caller still needs its own body afterwards, wrap the flow-ref in an enrich. When the call is the flow's last step, it needs nothing around it.
flows:
- name: opportunity-outcome
source: { connector: api, type: http, settings: { path: /opportunities/outcome, method: POST } }
process:
- type: switch
name: route-outcome
cases:
- when: body.outcome == "won"
process:
- type: enrich
name: close-won
body:
process:
- type: flow-ref
name: call-close-won
settings: { flow: close-won }
- name: close-won # no source: only flow-ref and tests reach it
process:
- type: odoo-call
name: set-won
settings: { connector: odoo, model: '"crm.lead"', method: '"action_set_won"', ids: body.opportunityId }Keep shared declarations in a globals file
When a project spans several files, put everything the flows share in octo.yaml: service, env, resources, the shared connectors, and processors. Put the flows in sibling files named for their area, such as contacts.yaml or opportunities.yaml. The runtime merges every file in the folder, so a flow in contacts.yaml uses the odoo connector declared in octo.yaml. See Multi-file Projects.
Name a suite after the flow it tests, and never give it the same base name as a flow file. dolphin test <folder> loads the whole folder for every suite, but a suite run by name (dolphin test x_test.yaml, which is how CI runs the samples) loads its companion x.yaml alone when one exists, and that file without octo.yaml has no connectors. sync-contacts_test.yaml next to contacts.yaml runs against the whole folder either way; contacts_test.yaml run by name would not.
samples/odoo-pipeline-sync/
octo.yaml # service, env, the odoo and http connectors
contacts.yaml # sync-contacts
opportunities.yaml # opportunity-outcome, close-won, close-lost
followups.yaml # stale-followups
sync-contacts_test.yaml
opportunity-outcome_test.yaml
close-won_test.yaml
close-lost_test.yaml
stale-followups_test.yamlGive every flow a suite
A dolphin suite runs one flow (flow: at the top), so every flow with logic in it gets its own <flow>_test.yaml. A single-file sample with several flows that need testing becomes a folder. Spies can still reach into a subflow through its own address (close-won.set-won), so the caller's suite can check the handoff while the subflow's suite checks what it does.
Name every block
Every block gets a name: kebab-case and verb-first, such as find-contact, create-lead or post-note. The name is what logs and traces print, what octo validate reports errors against (capture-lead.create-lead: ...), and the address a dolphin mock or spy uses (capture-lead.contact-exists[else].create-contact). An unnamed block is addressed by its type, which stops working as soon as a second block of that type joins the chain, and a log line saying set-payload failed doesn't say which one. A ref: step is addressed by the processor it references.
Reshape with CEL before reaching for foreach
Most reshaping is one expression. map, filter, exists and a ternary in a set-payload or multi-transform step beat a foreach that builds a list item by item. Keep foreach for steps that call something per item. Write multi-line CEL as a | block scalar so it reads as code.
- type: set-payload
name: summarize
settings:
value: |
{"created": body.filter(r, r.action == "created").size(),
"updated": body.filter(r, r.action == "updated").size(),
"contacts": body}Use switch for three or more branches
Branching three or more ways on the same value is one switch with a cases list and a default, not if blocks nested in each other's else. Two ways is an if.
Define repeated blocks once
A block configured the same way in several places becomes a processors: entry, and each use is a step with ref: naming it. Settings on the step override the processor's settings key by key.
processors:
- name: audit-log
type: log
settings: { level: info, message: '"handled " + eventID' }
flows:
- name: orders
process:
- ref: audit-logRead configuration from env
Secrets, hosts, ports and anything that changes between environments come from env. Mark secrets required: true so a missing one fails at startup, and give everything else a default. A literal key or URL in a block gets copied into every environment and every repository the file lands in.
env:
- name: ODOO_API_KEY
required: true
- name: ODOO_URL
required: true
- name: HTTP_PORT
default: "8080"Handle errors on purpose
For each step that can fail, choose how: a handle-errors block that recovers locally, a flow-level error: chain that recovers the whole flow, or, on a block that has the setting (the REST, Odoo, Slack, Notion, Tavily and Parallel blocks), failOnError: false followed by an explicit check of its result. A step that can fail with none of these fails the flow, which is fine when that is the intent. Say so in a comment.
Make scheduled and retried work idempotent
A cron flow runs again tomorrow and a queue redelivers on failure, so a flow with side effects filters out the work already done. The Odoo stale-followups sweep only selects opportunities with ["activity_ids", "=", false], so a second run schedules nothing new.
Comment the why, not the what
A # comment explains why a step exists or why it is shaped the way it is. The YAML already says what it does. There is no description field on a block. A leaf block silently drops a key it doesn't know, so a description: you add documents nothing and fails no check.
# ✗ restates the block
# search for the contact
- type: odoo-search-read
name: find-contact
# ✓ says what the reader can't see
# =ilike matches the email case-insensitively; one id is all the branch needs.
- type: odoo-search-read
name: find-contactCheck a flow
scripts/check-flow-practices.mjs runs in CI over samples/, Dr. Octo and the MCP examples. It fails on a run of setters and on an unnamed block, and it checks that every rule id on this page is also taught by the MCP prompt and by Dr. Octo's best-practices skill:
node scripts/check-flow-practices.mjs