Workflows Integration

skill

Read, create, and update Workflows records through its REST API using an org Integration row.

Download .md

Workflows Integration

When to use

Use this skill when a task requires listing a user's automation workflows, inspecting a specific workflow's definition, reviewing or triggering executions of a workflow, or checking the status/result of a workflow run in the Workflows app. Invoke it whenever an org's Integration row for Workflows is present and the request involves automating or reporting on workflow activity rather than editing workflow definitions directly (workflow authoring is out of scope).

Tools

  • http-get — read workflows, executions, and execution details
  • http-post — trigger a new workflow execution
  • http-request — perform update/delete operations (PUT/PATCH/DELETE) if and when the API exposes them
  • write-file — stage large result sets (e.g., long execution lists or bulky execution payloads) instead of dumping them inline
  • send-message — escalate to a human when authentication fails or configuration is missing

Playbook

  1. Confirm the org has an active Integration row for the Workflows app. If none exists, stop and use send-message to notify a human, naming "Workflows" and the scopes needed (API key with workflow read/execute access).
  2. To find a workflow, call http-get against /api/v1/workflows to list the authenticated user's workflows, most recent first. Match by name or description supplied in the task.
  3. Once you have a uid, call http-get against /api/v1/workflows/:uid to fetch full workflow detail (steps, inputs schema, current configuration) before triggering or reporting on it.
  4. To review history, call http-get against /api/v1/workflows/:workflow_uid/executions, optionally adding ?status= to filter (e.g., running, succeeded, failed) when the task asks for a specific execution state.
  5. To trigger a new run, call http-post against /api/v1/workflows/:workflow_uid/executions with the required inputs payload derived from the workflow's input schema. This enqueues an async job and returns HTTP 202 with a status_url — do not assume the run is complete.
  6. Poll the returned status_url, or call http-get against /api/v1/executions/:id directly, to check run status and retrieve the result once the execution finishes. Re-poll at reasonable intervals rather than looping tightly.
  7. If a result set (execution list or execution payload) is large, use write-file to stage it to disk rather than inlining the full content in your response; summarize the staged file's contents instead.
  8. If any call returns 401 or 403, do not retry with guessed credentials. Stop and use send-message to escalate to a human, naming the Workflows app and the specific scope that appears to be missing or invalid.
  9. Summarize outcomes in plain terms: which workflow ran, what inputs were used, the resulting status, and a link or reference to the execution id for follow-up.

Failure modes

  • Missing or inactive Integration row for Workflows: stop immediately, do not guess a base URL, escalate via send-message.
  • 401/403 on any call: credentials injected by the Integration row are invalid or lack scope; escalate via send-message naming the required scope rather than retrying.
  • Triggering an execution without validating required inputs against the workflow's schema (GET /api/v1/workflows/:uid) will produce a 202 that later fails; always fetch and honor the input schema first.
  • Treating the 202 response from POST .../executions as completion: the workflow is only enqueued. Always confirm completion via GET /api/v1/executions/:id.
  • Dumping a long executions list or verbose execution payload inline instead of staging it with write-file, which clutters output and risks truncation.

Done when

The requested workflow information has been retrieved, or the requested execution has been triggered and its final status (succeeded, failed, or another terminal state) has been confirmed via GET /api/v1/executions/:id, with large payloads staged via write-file and a clear summary returned. If blocked by missing integration or authentication failure, done when a human has been notified via send-message with the specific app and scope needed.