Action Catalog

What the Catalog Is

The Action Catalog is the one list of steps a workflow can run. Every app registers its steps in code, in the same typed shape, so Workflows treats an action from CRM, Invoices, or any other app the same way. A step that is not in the catalog cannot be used in a workflow.

The Registration Shape

An action is registered with registerAction() in src/core/workflows/catalog.js. Each action declares:

• Id. app.verb in lower case, such as core.notify. One id is registered once.
• Label. A plain sentence that says what the step does.
• Inputs and outputs. Each field has a name in lower case and a type: text, number, boolean, date, json, or record. An input may be required.
• Permission. The permission key a person needs to use the step, app.name, or signed_in for steps anyone signed in may use.
• Cost Limit. The most calls one run of the step may make (calls_per_run, 1 to 1000), and for steps that spend money, the most whole cents one run may spend (cents_per_run).
• Idempotency. How the engine knows a step is the same step: run_step (once per step of a run), input_hash (once per set of inputs), or none_safe (running it twice does no harm).
• Dry Run. Whether the step can show what it would do without doing it.
• Flags. money, deletion, and client_email. A flagged step needs a person's confirmation every time.

The validator checks every definition when the Worker starts. A bad definition stops startup with a sentence that names the action and each problem, so it never fails later inside someone's workflow.

Rules the Validator Enforces

• A flagged step needs a real permission, never signed_in.
• A flagged step supports dry run.
• A flagged step never uses none_safe idempotency.
• A step flagged money sets cents_per_run.
• A registered action is frozen: a workflow can read it and never change it.

Naming

Action ids are app.verb (invoices.send, crm.add_note). Permission keys are app.name. The app is the app that owns the action; an app never registers an action under another app's name.

Approval

A step with any flag cannot be marked automatic in a workflow. When a workflow reaches it, the run stops and waits for a signed-in person with the permission to confirm. Checking a workflow's steps against the catalog is validateStep(), which refuses an unknown action, an input the action does not have, a missing required input, and a flagged step marked automatic.

Atomic Actions

A safety-critical sequence, such as claiming a payment and then asking the payment service, is registered as one action with atomic: true and is never split into steps a workflow can reorder, skip, or repeat. The action does the whole sequence inside its own code, with its own idempotency rule.

The First Two Actions

• Tell People Something Is Waiting (core.notify). Rings the bell for the people named. Dry run says how many people it would notify.
• Wait Before the Next Step (core.wait). Pauses a workflow for 1 minute to 30 days and answers with the time to resume.

Shipping a Template

A provider can ship a workflow template to the accounts that have it through entitlements. A template has an id, a name, a whole-number version, and steps. When an entitled account takes the template, it is copied into the account as data (copyTemplate() in src/core/workflows/templates.js):

• The copy is the account's own. It can be edited like any workflow.
• The copy starts off. Only a person turns a workflow on.
• The copy records which template and version it came from, and keeps no live link. A later change to the template never overwrites it. When a newer version exists, the account is offered it and chooses (updateOffered()).
• Nothing is copied unless the account has the template, and every step must be in the catalog.

Where Templates Are Stored Planned

The provider's templates and the accounts' copies are stored by the Workflows app. Nothing is stored in the hub or in the code.