workflow-execution/lifecycle

107 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

StartWorkflowAsync and ExecuteWorkflowAsync methods for starting Workflow

To start a Workflow Execution in .NET, use either the StartWorkflowAsync() or ExecuteWorkflowAsync() methods in the Client. You must set a Workflow Id and Task Queue in the WorkflowOptions given to the method.

Example: Starting a Workflow Execution in .NET

var result = await client.ExecuteWorkflowAsync( (MyWorkflow wf) => wf.RunAsync(), new(id: "my-workflow-id", taskQueue: "my-task-queue"); Console.WriteLine("Result: {0}", result);

Getting Workflow Execution results using Workflow Handle

Use StartWorkflowAsync() or GetWorkflowHandle() to return a Workflow handle. Then use the GetResultAsync() method to await on the result of the Workflow. To get a handle for an existing Workflow by its Id, use GetWorkflowHandle().

Example: Getting results from an existing Workflow

var handle = client.GetWorkflowHandle("my-workflow-id"); var result = await handle.GetResultAsync<string>(); Console.WriteLine("Result: {0}", result);

DescribeAsync method to get current status of Workflow

Use DescribeAsync() on a Workflow handle to get the current status of the Workflow. If the Workflow does not exist, this call fails.

Workflow Id, Run Id, and Namespace uniquely identify a Workflow Execution

The Workflow Id, Run Id, and Namespace may be used to uniquely identify a Workflow Execution in the system and get its result.

Synchronous and asynchronous Workflow result retrieval

It's possible to both block progress on the result (synchronous execution) or get the result at some other point in time (asynchronous execution). In the Temporal Platform, it's also acceptable to use Queries as the preferred method for accessing the state and results of Workflow Executions.

workflow cancel - cancellation event and cleanup

Canceling a running Workflow Execution records a WorkflowExecutionCancelRequested event in the Event History. The Service schedules a new Command Task, and the Workflow Execution performs any cleanup work supported by its implementation.

workflow cancel by Workflow ID example

Example command to cancel a workflow by Workflow ID: temporal workflow cancel --workflow-id YourWorkflowId

workflow cancel by visibility query

Bulk cancellations to Workflow Executions can be sent using a visibility Query to cancel multiple workflows at once: temporal workflow cancel --query YourQuery

workflow describe - display execution information

The workflow describe command displays information about a specific Workflow Execution. It can also show the Workflow Execution's auto-reset points.

workflow describe flags

workflow describe command flags: --raw (bool, optional): Print properties without changing their format; --reset-points (bool, optional): Show auto-reset points only; --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow execute - establish and wait for completion

The workflow execute command establishes a new Workflow Execution and directs its progress to stdout. The command blocks and returns when the Workflow Execution completes. Use --event-details to relay updates to command-line output in JSON format.

workflow execute with input example

Example command to execute a workflow with input: temporal workflow execute --workflow-id YourWorkflowId --type YourWorkflow --task-queue YourTaskQueue --input '{"some-key": "some-value"}'

workflow execute flags

workflow execute command flags: --cron (string, optional): Cron schedule for the Workflow; --detailed (bool, optional): Display events as sections instead of table; --execution-timeout (duration, optional): Fail if execution lasts longer than DURATION, includes retries and ContinueAsNew tasks; --fail-existing (bool, optional): Fail if the Workflow already exists; --fairness-key (string, optional): Fairness key (max 64 bytes) for proportional task dispatch; --fairness-weight (float, optional): Weight [0.001-1000] for this fairness key; --headers (string[], optional): Temporal workflow headers in KEY=VALUE format; --id-conflict-policy (string-enum, optional): Determines how to resolve conflict, accepted values: Fail, UseExisting, TerminateExisting; --id-reuse-policy (string-enum, optional): Re-use policy for Workflow ID, accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning; --input/-i (string[], optional): Input value; --input-base64 (bool, optional): Assume inputs are base64-encoded; --input-file (string[], optional): Path to input file(s); --input-meta (string[], optional): Input payload metadata as KEY=VALUE pair; --memo (string[], optional): Memo using KEY="VALUE" pairs; --priority-key (int, optional): Priority key (1-5, lower = higher priority), default 3; --run-timeout (duration, optional): Fail if run lasts longer than DURATION; --search-attribute (string[], optional): Search Attribute in KEY=VALUE format; --start-delay (duration, optional): Delay before starting, can't use with cron; --static-details (string, optional): Static Workflow details for UIs, Temporal Markdown format, experimental; --static-summary (string, optional): Static Workflow summary for UIs, single line, experimental; --task-queue/-t (string, required): Workflow Task queue; --task-timeout (duration, optional): Fail if Workflow Task lasts longer than DURATION; --type (string, required): Workflow Type name; --workflow-id/-w (string, optional): Workflow ID, if not supplied, Service generates unique ID.

workflow execute-update-with-start - experimental

The workflow execute-update-with-start command sends a message to a Workflow Execution to invoke an Update handler and waits for the update to complete. If the Workflow Execution is not running, a new workflow execution is started and the update is sent. This is experimental.

workflow metadata - query user-set metadata

The workflow metadata command issues a Query to display user-set metadata like summary and details for a specific Workflow Execution.

workflow metadata flags

workflow metadata command flags: --headers (string[], optional): Temporal workflow headers in KEY=VALUE format; --reject-condition (string-enum, optional): Optional flag for rejecting Queries based on Workflow state, accepted values: not_open, not_completed_cleanly; --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow pause - experimental feature

The workflow pause command pauses a Workflow Execution. This is an experimental feature and may change in the future.

workflow query - retrieve execution state

The workflow query command sends a Query to a Workflow Execution by Workflow ID to retrieve its state. This synchronous operation exposes the internal state of a running Workflow Execution. You can query both running and completed Workflow Executions.

workflow result - wait for and print result

The workflow result command waits for and prints the result of a Workflow Execution.

workflow result flags

workflow result command flags: --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow signal - asynchronous notification

The workflow signal command sends an asynchronous notification (Signal) to a running Workflow Execution by its Workflow ID. The Signal is written to the History. When you include --input, that data is available for the Workflow Execution to consume.

workflow signal flags

workflow signal command flags: --headers (string[], optional): Temporal workflow headers in KEY=VALUE format; --input/-i (string[], optional): Input value; --input-base64 (bool, optional): Assume inputs are base64-encoded; --input-file (string[], optional): Path to input file(s); --input-meta (string[], optional): Input payload metadata as KEY=VALUE pair; --name (string, required): Signal name; --query/-q (string, optional): SQL-like Query List Filter, must set either --workflow-id or --query; --reason (string, optional): Reason for batch operation, only with --query, defaults to user name; --rps (float, optional): Limit batch requests per second, only if query present; --run-id/-r (string, optional): Run ID, only with --workflow-id, cannot use with --query; --workflow-id/-w (string, optional): Workflow ID, must set either --workflow-id or --query; --yes/-y (bool, optional): Don't prompt to confirm, only with --query.

workflow signal-with-start - signal or start

The workflow signal-with-start command sends an asynchronous notification (Signal) to a Workflow Execution. If the Workflow Execution is not running or is not found, it starts the workflow then sends the signal.

workflow stack - stack trace query

The workflow stack command performs a Query on a Workflow Execution using a __stack_trace-type Query to display a stack trace of the threads and routines currently in use by the Workflow for troubleshooting.

workflow stack flags

workflow stack command flags: --reject-condition (string-enum, optional): Optional flag to reject Queries based on Workflow state, accepted values: not_open, not_completed_cleanly; --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow start - initiate new execution

The workflow start command starts a new Workflow Execution and returns the Workflow- and Run-IDs.

workflow terminate - terminate execution

The workflow terminate command terminates a Workflow Execution. The reason is optional and defaults to the current user's name. The reason is stored in the Event History as part of the WorkflowExecutionTerminated event, which becomes the closing Event in the Workflow Execution's history.

workflow terminate vs cancel difference

Workflow code cannot see or respond to terminations. To perform clean-up work in Workflow code, use workflow cancel instead.

workflow terminate flags

workflow terminate command flags: --query/-q (string, optional): SQL-like Query List Filter, must set either --workflow-id or --query; --reason (string, optional): Reason for termination, defaults to message with current user's name; --rps (float, optional): Limit batch requests per second, only if query present; --run-id/-r (string, optional): Run ID, can only set with --workflow-id, do not use with --query; --workflow-id/-w (string, optional): Workflow ID, must set either --workflow-id or --query; --yes/-y (bool, optional): Don't prompt to confirm termination, only with --query.

workflow trace - real-time execution progress

The workflow trace command displays the progress of a Workflow Execution and its child workflows with a real-time trace. This view helps understand how Workflows are proceeding.

workflow trace flags

workflow trace command flags: --concurrency (int, optional): Number of Workflow Histories to fetch at a time; --depth (int, optional): Set depth for Child Workflow fetches, pass -1 to fetch child workflows at any depth; --fold (string[], optional): Fold away Child Workflows with specified statuses, case-insensitive, ignored if --no-fold supplied, available values: running, completed, failed, canceled, terminated, timedout, continueasnew; --no-fold (bool, optional): Disable folding, fetch and display Child Workflows within set depth; --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow unpause - experimental feature

The workflow unpause command unpauses a previously paused Workflow Execution. This is an experimental feature and may change in the future.

workflow unpause flags

workflow unpause command flags: --reason (string, optional): Reason for unpausing the Workflow Execution, defaults to message with current user's name; --run-id/-r (string, optional): Run ID; --workflow-id/-w (string, required): Workflow ID.

workflow update - synchronous call to workflow

An Update is a synchronous call to a Workflow Execution that can change its state, control its flow, and return a result.

workflow update describe - get update status

The workflow update describe subcommand returns information about an Update's current status given a Workflow Execution and an Update ID, including a result if it has finished.

workflow update execute - invoke and wait for update

The workflow update execute subcommand sends a message to a Workflow Execution to invoke an Update handler and waits for the update to complete or fail. You can also use this to wait for an existing update to complete by submitting an existing update ID.

workflow update result - wait for update completion

The workflow update result subcommand waits for the Update to complete or fail given a Workflow Execution and an Update ID, and prints the result.

workflow update result flags

workflow update result subcommand flags: --run-id/-r (string, optional): Run ID, if unset, updates the currently-running Workflow Execution; --update-id (string, required): Update ID, must be unique per Workflow Execution; --workflow-id/-w (string, required): Workflow ID.

workflow update start - start update and wait for acceptance

The workflow update start subcommand sends a message to a Workflow Execution to invoke an Update handler and waits for the update to be accepted or rejected. You can subsequently wait for the update to complete by using temporal workflow update execute.

workflow update start flags

workflow update start subcommand flags: --first-execution-run-id (string, optional): Parent Run ID, update is sent to last Workflow Execution in chain started with this Run ID; --headers (string[], optional): Temporal workflow headers in KEY=VALUE format; --input/-i (string[], optional): Input value; --input-base64 (bool, optional): Assume inputs are base64-encoded; --input-file (string[], optional): Path to input file(s); --input-meta (string[], optional): Input payload metadata as KEY=VALUE pair; --name (string, required): Handler method name; --run-id/-r (string, optional): Run ID, if unset, looks for Update against currently-running Workflow Execution; --update-id (string, optional): Update ID, if unset, defaults to a UUID; --wait-for-stage (string-enum, required): Update stage to wait for, only option is accepted, required to allow future CLI versions to choose default, accepted values: accepted; --workflow-id/-w (string, required): Workflow ID.

workflow update-options - modify workflow execution properties

The workflow update-options command modifies properties of Workflow Executions. It can override the Worker Deployment configuration of a Workflow Execution, which controls Worker Versioning.

workflow update-options to auto_upgrade example

Example command to force Workers in current Deployment to execute next Workflow Task with auto_upgrade behavior: temporal workflow update-options --workflow-id YourWorkflowId --versioning-override-behavior auto_upgrade

workflow update-options to pinned example

Example command to pin workflow execution to a Worker Deployment: temporal workflow update-options --workflow-id YourWorkflowId --versioning-override-behavior pinned --versioning-override-deployment-name YourDeploymentName --versioning-override-build-id YourDeploymentBuildId

workflow update-options to unspecified example

Example command to remove any previous overrides: temporal workflow update-options --workflow-id YourWorkflowId --versioning-override-behavior unspecified

workflow update-options flags

workflow update-options command flags: --headers (string[], optional): Temporal workflow headers in KEY=VALUE format; --query/-q (string, optional): SQL-like Query List Filter, must set either --workflow-id or --query; --reason (string, optional): Reason for batch operation, only with --query, defaults to user name; --rps (float, optional): Limit batch requests per second, only if query present; --run-id/-r (string, optional): Run ID, only with --workflow-id, cannot use with --query; --versioning-override-behavior (string-enum, required): Override the versioning behavior of a Workflow, accepted values: unspecified, pinned, auto_upgrade; --versioning-override-build-id (string, optional): When overriding to pinned behavior, specifies Build ID of version to target; --versioning-override-deployment-name (string, optional): When overriding to pinned behavior, specifies Deployment Name of version to target; --workflow-id/-w (string, optional): Workflow ID, must set either --workflow-id or --query; --yes/-y (bool, optional): Don't prompt to confirm, only with --query.

Give your agent this brain