Skip to content

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

  1. Can egress.http.call (or another registered capability) do it? → path A.
  2. Need credentials + designer connection type? → provider must also register a workflow_connection capability.
  3. 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.

  1. Connection: flows/connections/weatherstack.yaml (type: weatherstack, access_key: "$secret:…").
  2. Workflow step: type: service_call, capability_name: egress.weatherstack.current, path: /current, connection: weatherstack.
  3. Trigger: flows/triggers/*.yaml with target_workflow (see demo below).
  4. 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 on 404/409)
  • GET /internal/capabilities, GET /healthz

Register two capabilities:

  1. Step — name: egress.acme.lookup, kind: egress or workflow_step, metadata.public_paths + metadata.designer (step_type: service_call).
  2. Connection — name: acme.connection, kind: workflow_connection, designer connection_type: acme + form_fields (use secret: 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: true in engine/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

  1. Provider logs show successful register + heartbeats.
  2. GET http://capability-registry:8080/v1/registry/capabilities lists egress.acme.lookup and acme.connection.
  3. Workflow reload / deploy; run via Gateway path or POST /run/acme_lookup_demo.
  4. Trace shows service_call → provider path; secrets never appear in workflow YAML or provider logs as plaintext from Git.