save_workflow

save_workflow saves steps as a workflow — a new draft, or, with a workflow_id, the next version of a saved one. Build and validate the steps with build_workflow first.

A draft never runs by itself. run_workflow runs it by hand (a dry run by default); its schedule, webhook, or CRM trigger only starts firing after a person activates it in OnFire workflows — no tool does that.

The steps are checked exactly as build_workflow checks them and saved as checked: independent steps placed side by side, and anything the check filled in itself kept. filled_in lists what was filled in; side_by_side and rearranged report any reordering.

Confirmation flow

A new workflow is saved only on the user’s explicit yes.

The first save of a new workflow saves nothing and returns confirmation_required with:

• recap — when it runs, what it reads, what each step says its own fields are, what it changes, what happens to records already in the CRM, and not_given (the defaults nobody chose).
• user_facing_message — show the user every line of it.
• confirmation_token — pass it back on the next save, after the user says yes.

Show the message, wait for an explicit yes, then save again with the same steps and the token. A changed step needs a new message and a new yes.

A new version of a saved workflow (workflow_id) saves straight away — unless it adds a text-match condition the saved version didn’t have, in which case it too returns confirmation_required (naming the new matches) and saves only on the user’s yes.

Validation and blocking conditions

Steps with problems are still saved, with a validation block (valid, errors, warnings, each pointing at a step) — fix them and save again. Two things block a save outright:

• A failing SQL step. SQL-holding steps are previewed on 3 real rows first; if one fails (sql_step_fails), nothing is saved. Fix the SQL and rebuild.
• An unmatched data lookup. A step that looks your people or companies up in OnFire’s data with no match step before it saves nothing (customer_data_unmatched) — add the match and rebuild.

Every SQL step also needs its plain-language description; a missing one, or one that names a table, data source, or raw field, is refused. An update that changes the SQL but keeps the old description is refused too (sql_description_unchanged).

After saving

Tell the user it’s a draft they must review and activate in OnFire workflows (no tool activates it), and end your reply with the returned open_link exactly as given — [Open workflow](…), never the bare address. If the workflow emails, the answer’s emails names who will receive each one.

Inputs

Parameter	Type	Required	Description
name	string	Yes	The workflow’s name, e.g. “Weekly developer-growth stamp”.
steps	object[]	Yes	The workflow as steps — the last build_workflow answer’s steps.
description	string	No	What it does, in a sentence, for the people who’ll read it. With workflow_id, rewrite it per version.
workflow_id	string	No	Save as the next version of this workflow instead of a new one.
expected_version	integer	No	With workflow_id: the version you read. A newer saved version is refused rather than overwritten.
confirmation_token	string	No	The token a confirmation_required answer gave, passed only after the user said yes.
target_tenant_id	string	No	Super-tenant administrators only.

Notes

• Updating a saved workflow safely: read its current version with manage_workflows get and pass it as expected_version, so a concurrent change isn’t silently overwritten.
• Speak to the user in display names and labels, exactly as the recap does.