Skip to main content

Client Basics

Client calls are made by your application, not by a Step. The examples below use a Flow ID named order-123.

Start a Flow​

StartFlow creates a Flow execution and returns as soon as Dex Server accepts it. It takes a registered Flow, a business Flow ID, the start Step input, and StartFlowOptions.

The Flow ID is the identity your application chooses. Dex Server creates the Run ID. See Flow options for timeout, request idempotency, ID reuse, retry, initial Attributes, and configuration overrides.

run_id = await app_state.client.start_flow(
    app_state.client_apis, "order-123", "first order", start_options()
)

Example: examples/python/dex_examples/primitives/client-apis/controller.py

Stop a Flow​

StopFlow closes an active Flow. The default asks it to cancel cooperatively. You can instead terminate it immediately, or fail it with a reason.

await client.stop_flow("order-123", StopFlowOptions(reason="customer cancelled"))

Example: examples/python/dex_examples/products/job-post/controller.py

Invoke an RPC​

InvokeRPC calls a registered RPC handler on an active Flow and returns its result.

result = await client.invoke_rpc(flow.trigger, "order-123", "approved")

Example: examples/python/dex_examples/primitives/rpc/controller.py

Read and write Flow state​

Use Flow RPCs as the application boundary for Attribute, AttributeMap, Channel, and ChannelMap state. Define a typed RPC for each command or query, select only the state it needs, then call it with InvokeRPC. This keeps authorization, validation, locks, transactions, and state changes inside the Flow.

The Client still provides WaitForAttributeMatch as a blocking observation API. Use it when an application must wait for a known scalar Attribute condition rather than read an arbitrary state snapshot.