Integration end-to-end (new provider + workflow)¶
One-page happy path for adding a new egress-style capability and calling it from a workflow. Prefer composing an existing capability first (egress.http.call, Weatherstack, …). Only add a provider when you need a named capability, designer UX, or shared logic.
| Path | When | Start here |
|---|---|---|
| A — Workflow-only | Existing capability covers the need | Connections → workflow service_call → triggers |
| B/C — New provider | New reusable API / connector | This page → starter code → deploy |
Decide¶
- Can
egress.http.call(or another registered capability) do it? → path A. - Need credentials + designer connection type? → provider must also register a
workflow_connectioncapability. - Do not hardcode a new URL on the Orchestrator (
EGRESS_*_URL). Discovery is registry-only.
Path A — compose an existing capability¶
Example: call Weatherstack without writing a service.
- Connection:
flows/connections/weatherstack.yaml(type: weatherstack,access_key: "$secret:…"). - Workflow step:
type: service_call,capability_name: egress.weatherstack.current,path: /current,connection: weatherstack. - Trigger:
flows/triggers/*.yamlwithtarget_workflow(see demo below). - Copy:
flows/workflows/weatherstack_current_demo.yaml+flows/triggers/weatherstack-current-demo-http.yaml. SOAP over existing HTTP + XSLT: SOAP recipe (soap_http_xslt_demo) — no new provider.
Docs: Step types — service_call, Connections reference.
Path B — new provider (credentials)¶
Canonical example capability names (mirror Weatherstack):
| Piece | Example |
|---|---|
| Service | acme.service |
| Step capability | egress.acme.lookup |
| Connection capability | acme.connection |
| Connection type | acme |
| HTTP path | POST /lookup |
1. Implement the provider¶
Minimum surface (see Add a Capability Provider):
- Capability HTTP API (
POST /lookup) POST /v1/registry/services/register+ heartbeat ≈LEASE_TTL/2(re-register on404/409)GET /internal/capabilities,GET /healthz
Register two capabilities:
- Step —
name: egress.acme.lookup,kind: egressorworkflow_step,metadata.public_paths+metadata.designer(step_type: service_call). - Connection —
name: acme.connection,kind: workflow_connection, designerconnection_type: acme+form_fields(usesecret: true/$secret:placeholders for credentials).
service_call discovery is by capability name + version; kind is for catalog/filters. Engine egress services commonly use kind: egress; the contract also documents workflow_step — both work for steps.
Orchestrator merges named-connection fields into the JSON body sent to the provider (payload keys win on conflict). OAuth client secrets are stripped before egress (ADR 0011).
2. Connection + secret¶
# flows/connections/acme.yaml
name: acme
type: acme
api_key: "$secret:acme-api-key"
Store the real value in the runtime secret store — never commit plaintext credentials. See Secrets and Connections howto.
3. Workflow + trigger¶
# flows/workflows/acme_lookup_demo.yaml
name: acme_lookup_demo
group: Examples
description: Calls egress.acme.lookup via the capability registry.
steps:
- id: lookup
type: service_call
capability_name: egress.acme.lookup
capability_version: "^1.0"
path: /lookup
connection: acme
payload_from: initial
timeout_seconds: 30
- id: done
type: log
message: "Acme lookup finished"
# flows/triggers/acme-lookup-demo-http.yaml
name: acme-lookup-demo-http
target_workflow: acme_lookup_demo
invocation:
type: http
http_method: POST
gateway_public_path: /v1/api/examples/acme-lookup
gateway_auth_mode: none
Prefer separate trigger documents under flows/triggers/ over embedding invocation: in the workflow (same pattern as Weatherstack). Inline invocation still works for small demos.
4. Deploy wiring¶
Follow Deploy integration:
- Code under
engine/services/<name>/ capability_provider: trueinengine/deploy/engine-images-manifest.yaml- K8s deployment/service + kustomize + CI lists
- Wiki microservice page under
engine/reference/microservices/ - Enforce with
engine/tests/test_capability_provider_architecture.py
5. Registry URL (do not mix ports)¶
| Context | CAPABILITY_REGISTRY_URL |
|---|---|
| In-cluster / Compose service DNS | http://capability-registry:8080 |
| Host browser / curl via Compose publish | http://localhost:8093 (mapped to container 8080) |
Set SERVICE_URL to the URL Orchestrator uses (in-cluster DNS), not localhost.
Verify¶
- Provider logs show successful register + heartbeats.
GET http://capability-registry:8080/v1/registry/capabilitieslistsegress.acme.lookupandacme.connection.- Workflow reload / deploy; run via Gateway path or
POST /run/acme_lookup_demo. - Trace shows
service_call→ provider path; secrets never appear in workflow YAML or provider logs as plaintext from Git.