Build And Manage Automations

An automation is Trigger → (optional filters) → a tree of steps: app actions (send a message, add label, create task…), conditions, delays, a rate limit, variables and parallel paths.

References — load on demand, never all at once

A typical build needs 4–6 of these. If your harness supports subagents, push broad catalog sweeps and multi-schema reads into a subagent and keep only its conclusions.

Prerequisites

• Site + auth. A token with the Set Up Automations scope and the target metaSiteId (see Automations API Catalog (opens in a new tab) §1). Lock one site for the whole task; confirm it before the first write. Never print tokens or auth headers.
• What the user wants, concretely enough to pick a trigger and each side effect. Ask only what you can’t find out from the site’s catalog or data.

Workflow — keep the stages separate

For status-only requests, go directly to Automations Activation Status (opens in a new tab); it requires no planning or rebuilding of the automation. Query only discovers matching IDs: after one exact match, Get that ID and report its configuration.status. Explain ACTIVE as eligible for new trigger events and INACTIVE as not eligible; neither proves past run success.

0. Feasibility — Automations API reference (opens in a new tab)

Check the request against what the public APIs and the builder support before planning. Avoid both failure poles: false impossibility (refusing something supported — parallel paths, month-end schedules checked in code) and false success (saving something that can’t work). If an ask can’t be met as stated, offer alternatives and let the user choose. For an update, Get the automation first and check origin / settings locks (Automations Validation and Persistence — included update restrictions (opens in a new tab)).

1. Resolve real components — Automations API Catalog (opens in a new tab), Automations Trigger Configuration (opens in a new tab), Automations Action Configuration (opens in a new tab)

Find the trigger and actions in this site’s catalog (Resolve Triggers with basicFieldsOnly; Resolve Actions filtered by appId/actionKey — it has no basicFieldsOnly; small pages; search locally). Never invent an appId, triggerKey or actionKey, and never reuse example or placeholder ids from these references (ids explicitly marked as fixed platform constants — e.g. the webhook filter id, the Forms app id, the owner role — are required as written). Decide by payload and input schemas, not display names. Hydrate only the shortlisted components with full schemas.

2. Skeleton — Automations Graph and Data Model (opens in a new tab)

Plan the structure only: trigger, step list with fresh uuid v4 ids and builder-format namespaces, connections, and a one-line note per step (what it does, which entity ids it needs). Hard rules (the builder breaks otherwise):

• exactly one root; a RATE_LIMIT, if any, is that root and the only one;
• every postActionIds / truePostActionIds / falsePostActionIds has at most one id;
• a single-parent tree — no joins, cycles, orphans, or MERGE. To “continue after both branches”, duplicate the downstream steps in each branch with fresh ids;
• parallelism only through SPLIT (alpha — see Automations Delays Variables and Branches (opens in a new tab)).

3. Configure one step at a time, top-down

For each step load only the matching reference, then:

1. Compute the step’s aggregated schema locally (Automations Graph and Data Model (opens in a new tab)): trigger payload (dynamic schema only after its filters are final) + each ancestor action’s output under its namespace (dynamic output only after that action’s mapping is final) + variables + identity enrichment. Only paths in it may appear in var("…").
2. Action input. Map every required field yourself, following the field-type rules in Automations Action Configuration (opens in a new tab) / Automations Mapping Expressions (opens in a new tab). For provider-owned settings, follow the configuration procedure and permissions required by the provider; do not invent its opaque mapping. Provider recipe required: Other opaque widgets require their dedicated published recipe; if none is available, explain that configuration requires manual setup in the automations builder.
3. Entity ids. Fields backed by an entity selector take ids, never display names. Get them through the owning vertical’s public API, or ask the user (Automations API reference (opens in a new tab)). A failed lookup means unknown, not doesn’t exist.
4. Expressions. Self-check every {{ … }} against Automations Mapping Expressions (opens in a new tab) / Automations Conditions (opens in a new tab) — builder-renderable functions and operators only; anything the condition panel can’t render becomes a CODE_CONDITION.

4. Validate → fix → loop — Automations Validation and Persistence (opens in a new tab)

Run the builder-renderability checklist (§4 there — the single pre-save gate; script its [code] items: graph, ids, namespaces, var() paths, field limits), then Validate Automation on the full unsaved object. Fix and re-validate; 2–3 attempts per error class, and re-read the owning reference instead of mutating blindly when an error repeats.

Hard gate: never create, edit configuration or activate until every applicable checklist item holds AND the final full Validate has no CRITICAL error. VALID alone is not enough: the builder re-validates on open, pins every error to its node, blocks Activate while any remains, and silently deletes or rewrites shapes the checklist forbids. Status-only deactivation follows §3 of that reference without requiring configuration repair. Creation restrictions do not require changing existing builder-supported nodes on an unrelated update.

5. Persist and hand off

• Create: Create Automation with origin: "USER", configuration.status: "INACTIVE" and no settings → Get it back on the same site and compare → give the user the name, id, status and edit link https://manage.wix.com/dashboard/<metaSiteId>/triggers/edit/<automationId>, and tell them the builder’s main button (Activate) turns it on → activate via the API (Update with status: "ACTIVE") only when the user asks.
• Update: if the user has been editing it in the builder, ask them to publish or discard there first (their draft is invisible to you) → Get with override schemas and current revision → change only what was asked → checklist + Validate → confirm first if the automation is ACTIVE (updates are live) or if you delete nodes (unless already authorized) → Update with the complete merged object, preserving origin/settings/status → Get the returned id back (preinstalled overrides can change ids).
• Report honestly: validated ≠ saved ≠ verified ≠ active. Never claim runtime behavior from validation alone. Test Automation executes real side effects — only with explicit consent.

Non-negotiables

• Use the API contracts in these references and the public Automations docs. Supported automationConfigMapping fields are described here even where the docs omit them; use the catalog’s configuration schema and preserve the mapping on updates.
• Builder renderability is part of correctness, not polish: the §4 checklist in Automations Validation and Persistence (opens in a new tab) gates Create, configuration edits and activation; deactivation uses its status-only procedure.
• Real ids from the site; no display names in id fields; no invented content (addresses, coupon codes, template ids).
• Obtain authorization for activating, live edits, deleting or test runs when the request does not already authorize that action. Do not ask again for an explicitly requested status change.