Skip to main content
Every workflow run executes in a context: tenant-wide (workspace), an Embedded Connect principal (external_user_id), or an internal Console user (user_id from a Console team fan-out). How you set that context depends on which trigger starts the run — not every Studio tab shows Run as. See also External triggers for config JSON and Run setup for Manual Run and saved defaults.

​
Run identity (four targets)

In Workflow Studio → Run setup → Manual, Run as sets workspace / one principal / principal segment / Console team for Manual Run only.

​
Who sets identity? (by trigger)

Manual Run as does not change cron, platform events, or inbound at fire time. Each trigger uses its own saved config (or the event). Saved Run setup defaults only pre-fill forms — they are not merged when a trigger fires.

​
Which trigger should I use?

​
Platform events (no Run as)

Platform events are reactive: each emission is about a specific principal or connection. Control sets external_user_id (and related fields) on the run from the event — you do not pick workspace vs segment on the Events tab. Match rules on the trigger:
  • event_type — required (connection.created, principal.deleted, …)
  • provider_filter — optional, only on connection.created / connection.revoked (google_account, composio_account, whatsapp, or omit for any)
  • segment_id — optional; when set, the workflow runs only if the event principal matches that segment (same membership rules as cron segments)
Composio link connections (Gmail, Slack, …) emit composio_account, not google_account. Use google_account only for direct Google OAuth in Embedded Connect. Example config (bootstrap on connect, Composio Gmail, optional segment gate):
Configure in Studio → Run setup → Events. REST: POST /workflows/{id}/triggers with "type": "platform_event".

​
Cron: principal segment vs Console team

For workflows with MCP steps using connection_resolution: principal:
  • Workspace cron → one run without external_user_id (usually wrong for per-customer sync).
  • Principal segment cron → Control starts one run per principal in the segment on each tick.
  • Console team cron → Control starts one run per team member (user_id) on each tick (Settings → Team & Members teams — not principal segments).
Embedded Connect sync pattern:
  1. On connect — platform event connection.created (not cron).
  2. Live / backfill — cron with Run as → Principal segment (e.g. segment with require_connection).

​
Inbound and API

  • Inbound — set Run as on the subscription and map webhook JSON fields to external_user_id when needed.
  • API — pass external_user_id, segment_id, or team_id in command: start params. See External triggers.

​
Provider filter vs segment vs team

Use different workflows or filters when bootstrap logic differs by provider. Use principal segment for end-customer cohorts. Use Console team for internal user batch runs.

​
Checklist for a new automation

  1. One customer vs many? → event/webhook/API vs cron + segment or cron + team.
  2. Principal MCP in the graph? → every run needs external_user_id or principal segment fan-out.
  3. AgentRuntime lifecycle (connect, revoke, suspend)? → platform event, not duplicate partner webhooks.
  4. External vendor HTTP? → inbound or API.
  5. Periodic polling? → cron + segment (customers) or cron + team (internal users) — not platform events.
  6. Testing? → Manual + test external_user_id.
  7. Save explicit trigger_payload / trigger_steps on each trigger.