# 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.