oxy-automations

Oxy automations

The reference is upstream and maintained — read it rather than guessing: https://www.oxygen-hq.com/docs/guide/build/automations (index, loops, task-types, variables).

This skill deliberately does not restate the schema. It carries the things that reference does not tell you, and the mistakes that cost time.

The file-naming trap

The canonical extension is .automation.yml.

• .procedure.yml is the legacy name. It is still accepted, so a workspace full of it keeps working and nothing warns you — which is exactly why it spreads. One production workspace has 18 automations, and every one of them is still .procedure.yml.
• .workflow.yml is no longer a recognised file kind at all. A file with that name is silently not an automation, and oxy run refuses it.
• oxy migrate-automations renames legacy files (and rewrites references to them); --dry-run previews. It is the only thing that reads .workflow.yml files for that purpose.

Write new files as .automation.yml. Do not copy the extension from a neighbouring file in the workspace you are editing — that is how the legacy name propagated in the first place.

Naming, and why the code disagrees with the docs

"Automation" is the current name for what used to be called a Procedure, and before that a Workflow. The sub-automation task is still type: workflow, and API payloads and stored run records still say workflow — those are wire and storage contracts, not stale naming to be tidied up. Seeing workflow in a payload does not mean you are looking at something deprecated.

Routes follow the same split: /automations/:id is canonical; /workflows/:id, /procedures, and /agentic-workflows are aliases.

Task-type gotchas

• A misspelled type: passes validation and fails only at run time. An unrecognised task type — type: sql, type: execute — is read as an "unknown" step rather than rejected, so oxy validate reports the file valid and the run fails on that step with unknown task type. Check every type: against the task-types page by eye, then run the automation; validation alone proves nothing here. (A wrong field inside a known type, such as query: instead of sql_query:, does fail validation.)
• {{ step_name }} renders as JSON rows, not as a table. A prior SQL step's result renders into a template as a compact JSON list of row objects ([{"region": "west", "total": 42}, …]). That is what an agent or formatter prompt wants, and what a loop iterates over — but SELECT … FROM {{ extract }} sends that JSON to the warehouse as SQL and fails. To chain SQL steps, either inline the earlier query as a CTE in the later step, or have the earlier step write a table (CREATE OR REPLACE TABLE …) and read the table by name.
• http_request is HTTPS-only and blocks private egress. Requests to localhost, cloud-metadata endpoints, and private IP ranges are refused unless that task opts in with allow_hosts. A task that works locally and fails in cloud is usually this, not a network problem.
• Partial failures are their own state. A run where some steps failed records as completed_with_errors, not as a failed run. Code and dashboards that only check for "failed" will report it as a success.