workflows: core concepts

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Use WorkflowStub to start Workflow from Client in Java

`WorkflowStub` is a proxy generated by the `WorkflowClient`. Each time a new Workflow Execution is started, an instance of the Workflow implementation object is created. One of the methods annotated with `@WorkflowMethod` can be invoked. As soon as this method returns, the Workflow Execution is considered complete.

Typed vs untyped WorkflowStub in Java

Typed `WorkflowStub` are useful because they are type safe and allow direct invocation of Workflow methods such as `@WorkflowMethod`, `@QueryMethod`, and `@SignalMethod`. An untyped `WorkflowStub` does not use the Workflow interface and is not type safe, but is more flexible with methods like `start`, `signalWithStart`, `getResults`, `query`, `signal`, `cancel`, and `terminate`. For untyped stubs, you rely on Workflow Type, Activity Type, Child Workflow Type, as well as Query and Signal names.

Call Dynamic Workflow with untyped WorkflowStub in Java

Create an untyped `WorkflowStub` with the dynamic Workflow name and call it. The dynamic Workflow implementation must be registered with the Worker at runtime. Use `Workflow.getInfo().getWorkflowType()` in the implementation code to check what type is running.

Start Workflow on regular schedule using Cron in Java

Use `WorkflowOptions.Builder.setCronSchedule()` to start a Workflow Execution on a regular schedule. This creates a Temporal Cron Job—a series of Workflow Executions that occur at the scheduled intervals. The default timezone for a Cron is UTC.

Workflow Id is recommended but not required in Java

Although not required, it is recommended to provide your own Workflow Id that maps to a business process or business entity identifier, such as an order identifier or customer identifier. Set it using `WorkflowOptions.Builder.setWorkflowId()`.

Java WorkflowOptions table reference

WorkflowOptions available in Java SDK: WorkflowId (String, optional but recommended, default: none), TaskQueue (String, required, default: none), WorkflowExecutionTimeout (Duration, optional, default: Unlimited), WorkflowRunTimeout (Duration, optional, default: Same as WorkflowExecutionTimeout), WorkflowTaskTimeout (Duration, optional, default: 10 seconds, max: 60 seconds), WorkflowIdReusePolicy (WorkflowIdReusePolicy, optional, default: AllowDuplicate), RetryOptions (RetryOptions, optional, default: Null/no retries), CronSchedule (String, optional, default: None), Memo (String, optional, default: None), SearchAttributes (Map<String, Object>, optional, default: None).

WorkflowIdReusePolicy values in Java

WorkflowIdReusePolicy has three values: AllowDuplicateFailedOnly (Workflow can start if earlier Execution failed, Canceled, or Terminated), AllowDuplicate (default, Workflow can start regardless of earlier Execution's closure status), RejectDuplicate (Workflow cannot start if there is an earlier Run).

WorkflowTaskTimeout maximum value in Java

The WorkflowTaskTimeout has a maximum accepted value of 60 seconds. The default is 10 seconds.

Search Attributes supported types in Java

The following Java types are supported for Search Attributes: String, Long, Integer, Short, Byte, Boolean, Double, OffsetDateTime, and Collection of the types in this list.

Get last successful completion result for Cron Job in Java

For a Temporal Cron Job, use `Workflow.getLastCompletionResult(String.class)` to get the result of the previous successful run. The method returns null if there is no previous completion. This works even if one of the Cron schedule runs failed—the next schedule will still get the last successful result if it ever successfully completed at least once.

Temporal Client usage restrictions in workflows

A Temporal Client cannot be initialized and used inside a Workflow. However, it is acceptable and common to use a Temporal Client inside an Activity to communicate with a Temporal Service.

ExecuteWorkflow API in Go SDK

To spawn a Workflow Execution, use the ExecuteWorkflow() method on the Go SDK Client. The ExecuteWorkflow() API call requires an instance of context.Context, an instance of StartWorkflowOptions, a Workflow Type name, and all variables to be passed to the Workflow Execution. The ExecuteWorkflow() call returns a Future (WorkflowRun), which can be used to get the result of the Workflow Execution.

Workflow Type name as function reference vs string in Go

If the invocation process has direct access to the function, pass the Workflow Type name as the function name without quotations. If the invocation process does not have direct access to the Workflow Definition, provide the Workflow Type as a string.

StartWorkflowOptions reference for Go SDK

StartWorkflowOptions fields: ID (string, optional, default: system-generated UUID), TaskQueue (string, required), WorkflowExecutionTimeout (time.Duration, optional, default: unlimited), WorkflowRunTimeout (time.Duration, optional, default: same as WorkflowExecutionTimeout), WorkflowTaskTimeout (time.Duration, optional, default: 10 seconds), WorkflowIDReusePolicy (WorkflowIdReusePolicy, optional, default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE), WorkflowExecutionErrorWhenAlreadyStarted (bool, optional, default: false), RetryPolicy (RetryPolicy, optional, default: none), CronSchedule (string, optional, default: none), Memo (map[string]interface{}, optional, default: empty), SearchAttributes (map[string]interface{}, optional, default: empty).

Custom Workflow ID recommendation and usage

It is recommended to provide your own Workflow ID that maps to a business process or business entity identifier, such as an order identifier or customer identifier. Set the ID field in StartWorkflowOptions.

Memo field in StartWorkflowOptions

The Memo field in StartWorkflowOptions is of type map[string]interface{} with a default value of empty. It stores non-indexed metadata about the Workflow Execution.

Get Workflow result using WorkflowRun.Get() in Go

The ExecuteWorkflow() call returns a WorkflowRun instance. Call Get() on the WorkflowRun instance, passing it a pointer to populate with the Workflow Execution result. This blocks progress on the result (synchronous execution).

WorkflowRun methods in Go SDK

WorkflowRun has three methods: GetWorkflowID() returns the Workflow ID of the invoked Workflow Execution, GetRunID() returns the Run ID of the initial Run in the series of Runs that make up the full Workflow Execution, and Get() takes a pointer and populates it with the Workflow Execution result.

Get Workflow result from different process in Go

The result of a Workflow Execution can be obtained from a completely different process by calling GetWorkflow() method on the Go SDK Client with the Workflow ID. Then call Get() on the returned WorkflowRun instance, passing a pointer to populate the result. A Run ID is optional if only one closed Workflow Execution has the same Workflow ID.

Workflow Execution Event History creation in Go

A request to spawn a Workflow Execution causes the Temporal Service to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Service then creates the first Workflow Task, resulting in the first WorkflowTaskScheduled Event.

Give your agent this brain