Workflows and connectors

Use workflows for standalone AI endpoints, ETL, cron, heavy pipelines and delegated asynchronous jobs. App APIs, CRUD and authorization belong in a backend. One durable workflow should own a job’s orchestration and persistence; do not replace that pipeline with a cron job calling a backend worker.

Preserve existing workflows when editing: read the saved graph, relevant runs and versions first, then update the complete graph while keeping unchanged IDs, edges, settings and triggers.

• Manual and HTTP workflows respond synchronously by default. Set the trigger config `responseMode:{literal:"async"}` for jobs that return a run ID to poll.
• `queued`, `running` and `waiting` are pending, even on HTTP 200. Only `succeeded` proves success; `failed` and `cancelled` are terminal failures.
• HTTP 202 means accepted, not completed.
• A file-producing agent’s output is `{output,files}`, and its schema describes `output`. Following nodes use `$.output` or `$nodes.agentId.out.output`; a terminal agent yields `run.result.output` plus `run.result.files`. Without files, the output is direct.

Cron is a supported trigger kind, evaluated in the requested timezone. Background AI on a schedule needs owner billing. After saving, require `schedule.synced`, then confirm with `rumata.getWorkflowSchedule` that it exists, is unpaused and has `nextRun`; retry with `rumata.syncWorkflowSchedule` if needed. Share a child workflow between HTTP and scheduled entry points.

1. Discover with `rumata.listConnectors` and `rumata.listSecrets`. Never hardcode credentials; reference them by name.
2. A new connector goes through draft, publish, install revision, then binding a connection with `listSecrets.secretId`. Refresh `listConnectors` afterwards.
3. A connector node pins a revision, operation and connection. The URL, method and credentials belong to the revision.
4. Test one installed operation before building an importer around it. A missing connection means an unbound credential.

For the connector catalog, see Connectors and Secrets.

For user-requested generation or ETL, authenticate and authorize in the backend, persist a unique owner-scoped job identity, then start a private workflow asynchronously and return the job ID. The workflow owns provider submission, bounded polling with durable waits, retry and backoff, transfer to project storage and the final write. Browser polling only observes state.

• Persist the external task ID before progressing, and copy expiring provider output into durable storage before marking success.
• Use a unique constraint on owner plus request key. A duplicate click returns the existing job; a conflicting payload is rejected.
• The gateway’s run name is a label, not an idempotency key. Do not promise exactly-once submission from it.
• An uncertain provider response is not a safe retry. Use provider idempotency or lookup by a stable reference; otherwise mark the submission uncertain and expose a recovery path.
• Never regenerate paid output to repair parsing or persistence. Resume unapplied successful runs.