> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced workflows

> Build and run deterministic automation graphs with triggers, HTTP actions, branching, and AI steps.

**Advanced workflows** (visual workflows) let operators compose deterministic automation graphs on a canvas. They complement [agent automations](/platform/automations), which use an LLM orchestrator and tool plan.

The feature is in Beta. It is gated by the `workspace-visual-workflows` flag for your organization.

## Where to find them

Open organization **Automations**. When advanced workflows are enabled, click **Advanced workflows** to open the list at `/org/{slug}/automations/visual-workflows`.

From there you can create a workflow, open the canvas editor, and inspect run history per workflow.

Advanced workflows are organization-scoped today. They do not appear on project-scoped automation pages.

## Agent automations vs advanced workflows

|                     | Agent automations                                          | Advanced workflows                                                 |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **Execution model** | LLM orchestrator picks tools from `toolConfig`             | Deterministic graph interpreter walks nodes in order               |
| **Triggers**        | Manual, schedule, GitHub, upload, Contentful               | Manual only (Phase 1)                                              |
| **Best for**        | Open-ended playbooks with GitHub, Slack, translation tools | Fixed HTTP calls, branching, and short AI prompts in a known graph |
| **Run history**     | Automation run history                                     | Per-workflow runs with per-node snapshots                          |

Use agent automations when the agent should decide which tools to call. Use advanced workflows when the steps, order, and branches are fixed.

## Build a workflow

1. Click **New workflow** on the advanced workflows list.
2. Add nodes from the picker: **Manual trigger**, **HTTP request**, **If / else**, or **AI agent**.
3. Connect nodes on the canvas. The graph must have exactly one trigger and every non-trigger node must be reachable from it.
4. Configure each node in the side panel.
5. Save. Workflows start in **draft** status; set **active** when you are ready to run them.

### Node types (Phase 1)

| Node               | Purpose                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manual trigger** | Entry point for manual runs. Exposes trigger input to downstream nodes.                                                                                 |
| **HTTP request**   | Calls a public HTTPS URL with `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Responses include status and a bounded body snippet (up to 8,000 characters). |
| **If / else**      | Evaluates a condition and follows the **true** or **false** outgoing edge.                                                                              |
| **AI agent**       | Sends a prompt to the workspace AI Engine model and stores the generated text on the node output.                                                       |

**For each** loop nodes appear in the picker but are not executable in Phase 1.

### Template expressions

HTTP URLs, if conditions, and AI prompts support `{{ ... }}` placeholders that resolve at run time:

* `{{ trigger.field }}` — value from the manual run input
* `{{ nodes.<nodeId>.field }}` — output from an upstream node (for example `{{ nodes.http-1.body }}`)

If conditions support comparison operators (`===`, `!==`, `==`, `!=`, `>`, `>=`, `<`, `<=`) after templates are resolved. Empty conditions evaluate to false.

### Graph validation

Saving rejects invalid graphs:

* Missing or multiple triggers
* Edges pointing at missing nodes
* Nodes not reachable from the trigger

## Run a workflow

From the editor, queue a **manual run**. Cloud creates a run record, enqueues execution, and updates each node as it progresses.

Run statuses: `queued`, `running`, `succeeded`, `failed`, `cancelled`, or `skipped`.

Each run stores a definition snapshot so you can inspect what executed even if the workflow definition changed later.

### Idempotency

Manual runs require an `idempotencyKey`. Reusing the same key for the same workflow returns the existing run instead of creating a duplicate.

## HTTP action constraints

HTTP nodes use the same SSRF-safe fetch path as other public outbound requests in Cloud:

* Only public HTTPS URLs are allowed
* Redirects are not followed automatically
* Non-2xx responses fail the node

Do not put secrets in URLs. Prefer short-lived tokens in trigger input when you must pass credentials.

## Permissions and API

Advanced workflow routes require an organization **operator** role (admin or localization manager). The feature flag must also be enabled.

Authenticated JSON API (session cookie or equivalent app auth):

| Method  | Path                                                  | Description                                        |
| ------- | ----------------------------------------------------- | -------------------------------------------------- |
| `GET`   | `/api/orgs/{slug}/visual-workflows`                   | List workflows (`status`, `projectId`, pagination) |
| `POST`  | `/api/orgs/{slug}/visual-workflows`                   | Create a workflow                                  |
| `GET`   | `/api/orgs/{slug}/visual-workflows/{id}`              | Read one workflow                                  |
| `PATCH` | `/api/orgs/{slug}/visual-workflows/{id}`              | Update name, status, project, or definition        |
| `GET`   | `/api/orgs/{slug}/visual-workflows/{id}/runs`         | List runs                                          |
| `POST`  | `/api/orgs/{slug}/visual-workflows/{id}/runs`         | Queue a manual run (`idempotencyKey` required)     |
| `GET`   | `/api/orgs/{slug}/visual-workflows/{id}/runs/{runId}` | Run detail with node snapshots                     |

Responses use resource-keyed envelopes (`visualWorkflow`, `visualWorkflows`, `run`, `runs`). Errors follow the standard `{ error, message, details? }` shape.

When the flag is off, routes return `forbidden` with `visual_workflows_feature_disabled`.

## Troubleshooting

| Symptom                                    | Likely cause                                                               |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| **Advanced workflows** link missing        | `workspace-visual-workflows` flag is off for the org                       |
| Save fails with graph errors               | Multiple triggers, orphan node, or broken edge — check validation messages |
| HTTP node fails with `http_error`          | Target returned a non-2xx status                                           |
| HTTP node fails with `http_request_failed` | Blocked URL, network error, or SSRF validation failure                     |
| AI node fails with `ai_agent_failed`       | AI Engine misconfiguration or provider error                               |
| Run stuck in `queued`                      | Workflow worker not processing — check deployment/workflow queue health    |

## Next

* [Automations](/platform/automations)
* [Integrations](/platform/integrations)
* [MCP server](/platform/mcp)