Skip to main content

Client Advanced

Wait for a Flow​

WaitForFlow waits for terminal Flow status. A bounded wait can return a long-poll timeout while the Flow is still open; call it again to keep waiting.

result = await client.wait_for_flow("order-123", timedelta(minutes=1))

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

Wait for a Step​

WaitForStepCompletion waits for one StepExecutionID while the Flow continues. It confirms completion but does not return the Step output.

await client.wait_for_step_completion("order-123", StepExecutionId("ChargeOrder"), timedelta(minutes=1))

Example: examples/python/dex_examples/products/order-processing/controller.py

Wait for an Attribute match​

WaitForAttributeMatch waits until an Attribute satisfies a typed scalar comparison and returns the matched current value. It targets the current active run. For an AttributeMap, also supply the instance.

String and Boolean values support equal and not-equal. Integer and floating-point values also support greater-than, greater-than-or-equal, less-than, and less-than-or-equal. A missing Attribute never matches.

Use an application-owned revision Attribute when callers need to refresh after state changes. Wait for a value greater than the last revision, then invoke a Describe or read RPC. Revision is a watermark: rapid changes may be coalesced into one returned value.

revision = await app_state.client.wait_for_attribute_match(
    flow_id,
    app_state.job_post.update_version,
    AttributeMatch.greater_than(required_int_query("lastRevision")),
    timedelta(seconds=30),
)

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

Object, bytes, null, blob-backed, non-finite floating-point, cross-type, and invalid ordering comparisons are rejected. The wait is available with Temporal only; Cadence returns Unimplemented. See Wait for Attribute Match for the complete revision pattern.

Describe a Flow​

DescribeFlow returns the current or latest run's IDs, Flow type, status, and start time. It does not require the Flow to be active.

info = await client.describe_flow("order-123")

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

Search Flows​

SearchFlows returns one page of Flow runs matching a visibility query. Search finds Flow instances; DescribeFlow describes one known Flow ID. Pass the returned page token to continue a search.

page = await client.search_flows("FlowType = 'ClientApisFlow'", 20, "")

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

Skip a Timer​

SkipTimer makes one waiting Timer ready immediately. Choose the Step execution and either the Timer's condition ID or its zero-based condition index.

await client.skip_timer("order-123", StepExecutionId("ChargeOrder"), TimerId.by_condition_id("retry"))

Example: examples/python/dex_examples/products/order-processing/controller.py

Update FlowConfig​

UpdateFlowConfig changes the FlowConfig.

await client.update_flow_config("order-123", FlowConfig(continue_as_new_threshold=1_000))

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

Trigger continue-as-new​

TriggerContinueAsNew asks an active Flow to roll its history into a new run.

await client.trigger_continue_as_new("order-123")

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

Time travel​

TimeTravel creates a new run from a point in an existing Flow's history.

new_run_id = await client.time_travel("order-123", TimeTravelOptions(type=TimeTravelType.BEGINNING, reason="code fix"))

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