Connectors overview
A service_task step names a logical action (e.g. disburse-funds,
notify) rather than a concrete integration. At the tenant level, that
action is bound to a connector type and a config — the indirection
lets the same workflow model call different real endpoints per tenant, or
per environment, without touching the workflow itself. Bindings are managed
via GET/PUT/DELETE /connectors.
How a service task executes
The compiled step resolves to a queued, task-token callback: the state
machine sends a message (action, tenant, project, execution id, step id,
task token, and the current workflow state as input) to a work queue and
pauses. A connector worker consumes the message, resolves the tenant’s
binding for that action, calls the matching handler, and reports the result
back via a Step-Functions task-token success/failure call. On success the
result lands at $.tasks.<stepId> in the workflow state, same as any other
step result (see Workflows § reserved namespaces).
A failed message that a connector can’t complete dead-letters after a bounded
number of receive attempts; the workflow’s own retry/catch on the step is
what determines whether the step retries or an error branch is taken — the
connector’s job is only to map the outcome (success, typed failure, or
transport failure) into a SendTaskSuccess/SendTaskFailure call, never to
reimplement workflow-level retry itself.
Built-in types
| Type | Purpose |
|---|---|
echo | Returns the input verbatim — for wiring and testing a workflow’s shape before a real integration exists |
noop | Succeeds immediately with an empty result — a deliberate no-op step |
http | Calls an external HTTP endpoint with auth, request/response mapping, timeout and retry — see HTTP connector |
Config secrecy
A connector config may carry a secret (an API key, a bearer token). Configs are encrypted at rest under a per-tenant envelope before being written — never plaintext — and only decrypted by the connector worker at call time. See Encryption at rest.
Adding a binding
curl -sS -X PUT "$RULEFLOW_API/api/connectors/notify" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "type": "echo", "config": {} }'
A workflow’s service_task with "action": "notify" then resolves to this
binding at runtime, for this tenant, in every environment — bind a different
config (or type) per tenant to point the same logical action at a different
real endpoint.