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

# Workflow Triggers

> Choose the right trigger for manual runs, schedules, API requests, site lifecycle events, WAN health events, and workflow chaining.

A trigger decides when a workflow starts and what context enters the graph. Choose the trigger before you design the rest of the workflow; the trigger determines the first variables your actions and conditions can use.

## Prerequisites

Before you configure triggers, make sure you have:

* Permission to create or edit workflows.
* A clear source event for the automation.
* A sample payload or site/WAN event you can test against.
* A workflow authorization if the workflow will call SDX APIs on behalf of a user.

## Trigger Categories

| Category              | Triggers                                                                               | Use when                                                                  |
| --------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Operator and schedule | Manual Trigger, Scheduled Trigger                                                      | A user starts the workflow, or the workflow runs on a recurring schedule. |
| Workflow composition  | Trigger by Another Workflow, Subflow Trigger                                           | You want reusable automation blocks or nested logic.                      |
| API                   | API Trigger (Synchronous)                                                              | An external request needs a workflow-generated response.                  |
| Site lifecycle        | Site Added, Site Removed                                                               | Site onboarding or removal should trigger follow-up work.                 |
| Site health           | Site Offline, Site Online                                                              | A site health event should notify, enrich, or remediate.                  |
| WAN health            | WAN Interface Offline, WAN Interface Online, WAN Packet Loss, WAN Packet Loss Resolved | WAN failover or quality events should drive operations.                   |

## Manual Trigger

Use **Manual Trigger** for operator-controlled workflows. This is the safest starting point for diagnostics, one-off reports, and workflows that need human intent before they run.

Good uses:

* Run a site health check on demand.
* Generate a one-time operational summary.
* Trigger a controlled workflow during an incident.

## Scheduled Trigger

Use **Scheduled Trigger** for recurring work. Scheduled workflows are dispatched by the workflow service and are best for audits, cleanup, reports, and periodic synchronization.

Good uses:

* Daily inventory or metadata checks.
* Weekly report generation.
* Recurring checks for missing tags, offline sites, or policy drift.

## API Trigger (Synchronous)

Use **API Trigger (Synchronous)** when an external system calls a workflow and expects an immediate HTTP response.

Synchronous workflows:

* Must be active before they accept requests.
* Receive request payload, headers, query parameters, method, URL, user agent, and IP address in the initial context.
* Can use JWT claims when an authorizer validates a request.
* Should finish quickly enough for an HTTP caller.

<Warning>
  Keep synchronous workflows small and predictable. Long-running device jobs, multi-site loops, or human approval steps are better handled asynchronously.
</Warning>

## Site And WAN Event Triggers

Use platform event triggers when the workflow should react to SDX telemetry:

* **Site Offline:** a site has stopped checking in long enough to be marked offline.
* **Site Online:** a site resumes heartbeats after being offline.
* **WAN Interface Offline:** a WAN failover interface goes offline.
* **WAN Interface Online:** a WAN failover interface comes online.
* **WAN Packet Loss:** a WAN interface experiences packet loss.
* **WAN Packet Loss Resolved:** packet loss recovers.
* **Site Added** and **Site Removed:** the site lifecycle changes.

These triggers are useful because the workflow starts with context from the event. Enrich that context with **Get Site**, **Get WAN Tunnel**, and **Get Resource Tags** before you decide what to do next.

## Workflow Chaining

Use **Trigger by Another Workflow** when one workflow should be callable by another workflow. This keeps common logic centralized.

Good uses:

* A shared notification formatter.
* A reusable tagging routine.
* A common external ticket creation flow.

SDX prevents self-triggering and circular workflow dependencies when workflows are saved.

## Webhook-Style Inbound Requests

The workflow service supports system-generated inbound endpoints for workflows that are configured for external triggering. Treat those endpoints like credentials:

* Store external caller secrets in the vault.
* Validate payloads before taking action.
* Prefer synchronous API workflows only when the caller needs an immediate response.
* Use normal workflow logs to inspect accepted requests and failed nodes.

## Next Step

<CardGroup cols={2}>
  <Card title="Build workflows" icon="workflow" href="./building-workflows" arrow="true">
    Add actions, conditions, variables, and tests.
  </Card>

  <Card title="Use authorizations" icon="user-check" href="./authorizations" arrow="true">
    Understand user-delegated workflow access.
  </Card>
</CardGroup>