Implementing a Workflow participant#
A participant is an independently deployed service or application that publishes events, executes approved capabilities or hosts human interactions. The authoritative integration surface consists of versioned JSON, OpenAPI and schema contracts. A participant can use a .NET adapter, but it does not need to share Workflow's runtime types, database or UI framework.
Separate capability registration from deployment enrollment. Infrastructure establishes the workload identity, allowed callers, tenant scope, transport allocation and protected execution route. Workflow's catalog then records and approves what that participant is allowed to expose.
Implementation sequence#
- Define the capability's input, result and business outcome meanings.
- Implement durable acceptance, effect handling and authoritative operation receipts.
- Provide query and cancellation behavior consistent with the operation contract.
- Provision the participant identity and trusted HTTPS or RabbitMQ route through deployment owners.
- Register supported schemas and the participant manifest.
- Obtain approval from a distinct authorized human.
- Create an approved service binding and select it in a process definition.
- Verify allowed, denied, duplicate, uncertain and restart cases before activating the integration.
A visible route is not proof of working credentials or connectivity. The administration readiness state ConfiguredNotProbed confirms configuration presence, not successful live execution.
Catalog APIs#
The documented base path is /api/workflow/v1.
| Method and relative route | Purpose |
|---|---|
POST catalog/{tenant}/{kind} |
Submit a schema, manifest, role or binding |
POST catalog/{tenant}/{kind}/{id}/{version}/approve |
Approve the exact immutable digest |
GET catalog/{tenant} |
Read the authorized approved catalog |
POST integrations/{tenant}/drafts |
Save a draft with expectedRevision |
POST integrations/{tenant}/drafts/{id}/submit |
Submit the saved draft revision |
POST integrations/{tenant}/retire |
Retire content with digest and revision checks |
URL-encode identifiers, including schema URNs. Schema submission uses schemaRef, version, ownerId, vocabulary and schema. The documented vocabulary is workflow-domain-schema/1, with references shaped as urn:sk:domain:<owner>:<version>:<name>. Remote schema fetching and permissive fallback for unsupported keywords are excluded.
Registration requires registry.submit and participant enrollment. Approval requires human-only registry.approve, a distinct PrincipalId and the exact digest. Repeating identical immutable content is safe; changing content at an existing immutable identity is a conflict.
HTTPS participant transport#
The documented execution adapter posts to these relative paths under the trusted HttpsBaseUrl:
| Path | Participant responsibility |
|---|---|
/v1/commands |
Accept or reconcile the immutable command |
/v1/query |
Return the authoritative operation receipt/status |
/v1/cancellations |
Resolve a cancellation request against durable effect state |
The adapter requires HTTPS and does not follow redirects. It selects protected credential configuration by Workflow:Execution:Credentials:{OwnerId}. Do not expose credential values in BPMN, catalog documents or business messages. An arbitrary HTTP business endpoint is not a durable Workflow participant merely because its URL is reachable.
RabbitMQ participant transport#
A trusted ExecutorRoute selects the exchange, routing key, subscriber and enrolled responder. The participant commits its operation/effect/receipt boundary before acknowledging the command. Reply notifications do not replace its durable receipt store.
A release-dependent extension adds route-specific rabbitResponse settings: queue, exchange, routingKey and brokerUsername. It separates independent responder identities and reply routes on the existing executor broker connection. The matching Worker and API validation build must be deployed before such routes are enrolled; older Workers do not interpret the extension correctly.
Do not copy another participant's broker identity or change a pinned route while in-flight operations need it for reconciliation. Validate response provenance and the receipt's tenant, owner, operation and attempt independently.
Integration acceptance#
Exercise schema rejection, wrong identity, wrong tenant, duplicate submission, changed-payload conflicts, lost responses and cancellation races. Demonstrate receipt recovery after a participant restart and prove that the participant cannot access Workflow's private tables. Use the exact supported release contracts for implementation details and continue with durable operations.