Calling services
A call-transport step sends a payload to an address and waits for the answer. The address kind decides which transport makes the call; the transport’s configuration decides where the call goes. The definition names a service or a target, never a URL or a broker, so the same definition runs unchanged in every environment.
Choosing an address kind
| Kind | Use it for | Definition names | Configuration supplies | Package |
|---|---|---|---|---|
endpoint | Your own services, called by service name, method and path | Service name, method, path | Base URL and headers per service | StellaOps.Workflow.Transport.Http |
http | Any HTTP API, called by target name | Target, method, path | Base URL and headers per target | StellaOps.Workflow.Transport.Http |
graphql | A GraphQL API | Target, query, operation name | URL and headers per target | StellaOps.Workflow.Transport.GraphQL |
rabbit | A RabbitMQ consumer: a plain publish, or a command with a correlated reply | Exchange, routing key, optional command | The broker connection | StellaOps.Workflow.Transport.RabbitMq |
endpoint and http behave the same on the wire. Use endpoint for services you own and address by service name, http for external APIs; they have separate configuration sections, so you can give each its own headers.
Registering the transports
Register one transport package per kind your workflows use:
/// <summary>Registers a transport for each address kind the host's workflows use.</summary>
public static IServiceCollection AddWorkflowTransports(this IServiceCollection services, IConfiguration configuration)
{
// `endpoint` (WorkflowEndpointTransport:Services) and `http` (WorkflowHttpTransport:Targets).
services.AddWorkflowHttpTransport(configuration);
// `graphql` (WorkflowGraphqlTransport:Targets).
services.AddWorkflowGraphqlTransport(configuration);
// `rabbit` (WorkflowRabbitTransport): one broker connection per host.
services.AddWorkflowRabbitTransport(configuration);
return services;
}
Register the package of every kind your workflows use. On Stella.Engine, the default runtime provider, a host whose workflows use a kind without its package stops at start with WFIMP010, which names the missing module (for example transport.http). On Stella.InProcess, every call of that kind fails with an error that names the missing transport; nothing is sent, queued or acknowledged.
endpoint
// An `endpoint` call: the service name resolves through WorkflowEndpointTransport:Services.
// The response is kept under "result.stock" for the following steps.
.Call<object>(
"Read stock level",
new EndpointAddress("inventory", "/items/stock-level"),
WorkflowExpr.Obj(WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku"))),
resultKey: "stock")
.Set("onHand", WorkflowExpr.Path("result.stock.onHand"))
new EndpointAddress(serviceName, path, method = "POST"). Configuration:
{
"WorkflowEndpointTransport": {
"Services": {
"inventory": {
"Url": "<base URL of the inventory service>",
"Headers": { "X-Api-Key": "<key>" }
}
}
}
}
WorkflowEndpointTransport__Services__inventory__Url=https://inventory.contoso.example/api/
WorkflowEndpointTransport__Services__inventory__Headers__X-Api-Key=<key>
- The request goes to the base URL joined with the path; a trailing slash on the URL and a leading slash on the path are optional, and a path in the base URL is kept (
https://inventory.contoso.example/api/items/stock-levelabove). - Service names are not case-sensitive. An unknown service, or one without a URL, fails the call before any request:
Configure WorkflowEndpointTransport:Services:<name>:Url. - The payload is sent as JSON; the response body, when it is JSON, is the result.
- The
endpointkind uses the HTTP client, timeout and retries ofWorkflowHttpTransport.
http
// An `http` call: the target resolves through WorkflowHttpTransport:Targets.
// A failed or unreachable call runs whenFailure, a timed-out call whenTimeout;
// "result.lastFailure" describes the failure.
.Call(
"Place purchase order",
new HttpAddress("purchasing", "/purchase-orders"),
WorkflowExpr.Obj(
WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku")),
WorkflowExpr.Prop("quantity", WorkflowExpr.Path("state.reorderQuantity"))),
whenFailure: failed => failed
.Set("orderFailure", WorkflowExpr.Path("result.lastFailure.message"))
.ActivateTask("Place order manually"),
whenTimeout: timedOut => timedOut
.Set("orderFailure", WorkflowExpr.String("the purchasing service did not answer"))
.ActivateTask("Place order manually"))
new HttpAddress(target, path, method = "POST"). Configuration:
{
"WorkflowHttpTransport": {
"TimeoutSeconds": 30,
"RetryCount": 3,
"Targets": {
"purchasing": {
"Url": "<base URL of the purchasing API>",
"Headers": { "Authorization": "Bearer <token>" }
}
}
}
}
| Key | Default | Effect |
|---|---|---|
TimeoutSeconds | 30 | The timeout of one attempt; the whole call, retries included, gets three times this value |
RetryCount | 3 | Retries of a failed attempt, with exponential backoff from one second and jitter |
Targets:<name>:Url, Headers | none | The base URL and the headers of a target |
One circuit breaker covers all endpoint and http calls of a host, whatever their service or target; GraphQL calls have their own. It opens for 15 seconds when half of at least five requests in 120 seconds fail, so one failing service can stop the calls to the others for that time. These values are fixed.
graphql
In C#, QueryGraphql sends a query to a GraphQL target. The variables are an expression, and QueryGraphql<TResponse> keeps the response under result.<resultKey> (the step name when no key is given); the non-generic forms keep no result. A QueryGraphql call builds with the warning WF021. The older overloads that take the variables from a C# delegate have no canonical form: a host on Stella.Engine that registers a workflow with them stops at start.
// A `graphql` call: the target resolves through WorkflowGraphqlTransport:Targets. The
// variables are an expression; the response body ({ "data": ... }) is kept under "result.supplier".
.QueryGraphql<object>(
"Find supplier",
new GraphqlAddress(
"catalogue",
"query Supplier($sku: String!) { supplier(sku: $sku) { id name } }",
"Supplier"),
WorkflowExpr.Obj(WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku"))),
resultKey: "supplier")
.Set("supplierName", WorkflowExpr.Path("result.supplier.data.supplier.name"))
Configuration:
{
"WorkflowGraphqlTransport": {
"TimeoutSeconds": 30,
"RetryCount": 3,
"Targets": {
"catalogue": { "Url": "<URL of the catalogue GraphQL endpoint>", "Headers": {} }
}
}
}
Target names in this section are case-sensitive.
rabbit
RabbitAddress(exchange, routingKey, command, framing, expectReply) addresses a RabbitMQ consumer. With a command, the call sends a command and waits for the correlated reply, which a result key keeps:
// A `rabbit` command: the consumer of the exchange "inventory" and the routing key
// "stock.reserve" answers with a correlated reply, kept under "result.reservation".
// The step gives up after 30 seconds and runs its timeout branch.
.Call<object>(
"Reserve stock",
new RabbitAddress("inventory", "stock.reserve", "ReserveStock"),
WorkflowExpr.Obj(
WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku")),
WorkflowExpr.Prop("quantity", WorkflowExpr.Path("state.quantity"))),
whenFailure: failed => failed
.Set("reservation", WorkflowExpr.String("failed"))
.Complete(),
whenTimeout: timedOut => timedOut
.Set("reservation", WorkflowExpr.String("timed-out"))
.Complete(),
resultKey: "reservation",
timeoutSeconds: 30)
Without a command, the call publishes the payload and succeeds when the broker confirms it:
// A plain publish: no command, no reply; the call succeeds when the broker confirms it.
.Call(
"Announce reservation",
new RabbitAddress("inventory", "stock.reserved"),
WorkflowExpr.Obj(WorkflowExpr.Prop("orderId", WorkflowExpr.Path("state.orderId"))))
| Argument | Meaning |
|---|---|
exchange, routingKey | Where the message goes; both are required |
command | The command the consumer dispatches on; none for a plain publish |
framing | WorkflowRabbitCommandFraming.Envelope (the default): the body is a JSON envelope with the command name, a correlation id and the payload. Header: the body is the bare payload and the command name travels in a message header |
expectReply | true (default): the call waits for the reply with the same correlation id |
A reply’s error field (envelope framing) or error header (header framing) fails the call. No reply within the reply timeout runs the step’s timeout branch. A message the broker cannot route fails the call. Register the transport with AddWorkflowRabbitTransport(configuration), which installs the transport.rabbit module. Configuration:
{
"WorkflowRabbitTransport": {
"HostName": "rabbit.contoso.example",
"Port": 5671,
"VirtualHost": "/",
"UserName": "workflow",
"Tls": { "Enabled": true, "ServerName": "rabbit.contoso.example" },
"ReplyTimeoutSeconds": 30,
"ReplyQueueMode": "DirectReplyTo"
}
}
WorkflowRabbitTransport__Password=<password>
The host name has no default; a call without it fails. ReplyQueueMode is DirectReplyTo (the broker’s direct reply-to) or ExclusiveQueue (one exclusive reply queue per host). The header and field names of the framing are configurable (Configuration reference). Set both UserName and Password: without them the RabbitMQ client’s default user applies. Keep the password out of committed files.
Results
A typed call (Call<TResponse>, Call<TRequest, TResponse>, QueryGraphql<TResponse>, QueryGraphql<TVariables, TResponse>) keeps the response under result.<resultKey>, or result.<stepName> without a key, also when the call has a failure or timeout branch; an untyped call keeps no response. The next steps read it with a path. Copy what the workflow needs later into the state with Set, as the endpoint example above does with result.stock.onHand: the state is what the engine stores with the instance.
Failures and timeouts
| Situation | Without a branch | With whenFailure / whenTimeout |
|---|---|---|
| The service answers with a non-success status | The step fails. In a start or a task completion, the request answers 502 WorkflowTransportFailed; in a step resumed by a signal (after a timer, a signal or a child workflow), the signal is retried up to the delivery limit, then dead-lettered | The failure branch runs |
| The service cannot be reached (a failed connection after the retries, an open circuit breaker) | As above | The failure branch runs |
| The address is not configured | As above | The failure branch runs |
| The call times out | The step fails with the timeout error. In a start or a task completion, the request answers 500; in a step resumed by a signal, the signal is retried up to the delivery limit, then dead-lettered | The timeout branch runs |
A call times out when its step timeout passes, when the transport gives up (for endpoint, http and graphql, the attempt or total timeout of the resilience pipeline), or when it is cancelled other than by its caller. A failure or timeout branch reads the failure as result.lastFailure, on both runtime providers and for every address kind:
| Field | Content |
|---|---|
stepName | The step that failed |
operation | service:METHOD path for endpoint, target:METHOD path for http, target:operationName (or target) for graphql, exchange:routingKey for rabbit |
statusCode | The HTTP status that an endpoint or http call returned; null for graphql, rabbit and any timeout |
message | The transport error, for example “… could not be reached: …” or “… was not called: its circuit breaker is open.”, or the timeout message |
timedOut | true for a timeout |
WorkflowHandledBranchAction.Complete is the short form of a branch that only completes the instance.
Timeouts
Three timeouts apply, from the inside out:
- One attempt:
TimeoutSecondsofWorkflowHttpTransportorWorkflowGraphqlTransport(30 s). - One step: the
timeoutSecondsargument ofCallandQueryGraphql(the canonical step’stimeoutSeconds), wrapping all attempts. Without it a call gets one hour. - One engine operation:
WorkflowEngine:ExecutionTimeoutSecondswraps a start, a completion or a resume. Unset by default; leave it unset for workflows that run for days.
Testing calls
Replace a transport with your own implementation of IWorkflowEndpointTransport, IWorkflowHttpTransport, IWorkflowGraphqlTransport or IWorkflowRabbitTransport to record calls and script answers (Testing).
Pitfalls
- A URL in the definition. Definitions name services and targets; URLs belong in configuration.
- A missing transport package. On
Stella.Enginethe host stops at start withWFIMP010; onStella.InProcessthe calls of that kind fail at run time. Register a transport for every kind the workflows use, and validate stored definitions: the validator reports a missing module. - Retrying non-idempotent calls. The HTTP transport retries a failed attempt, and a failed step is retried from its signal. Make the called operation idempotent, for example with a request id in the payload.
- Secrets in headers. Header values come from configuration; put tokens in environment variables or a secret store.
- Long calls. A call blocks the instance for its duration. For work that takes minutes, use an external activity or a signal.
