Skip to main content

Class: WorkflowClient

Client for starting Workflow executions and creating Workflow handles.

Typically this client should not be instantiated directly, instead create the high level Client and use Client.workflow to interact with Workflows.

Extends​

  • BaseClient

Extended by​

Constructors​

Constructor​

new WorkflowClient(options?): WorkflowClient

Parameters​

options?​

WorkflowClientOptions

Returns​

WorkflowClient

Overrides​

BaseClient.constructor

Properties​

connection​

readonly connection: ConnectionLike

The underlying connection or NativeConnection | native connection used by this client.

Clients are cheap to create, but connections are expensive. Where it makes sense, a single connection may and should be reused by multiple Clients.

Inherited from​

BaseClient.connection

options​

readonly options: LoadedWorkflowClientOptions

Accessors​

workflowService​

Get Signature​

get workflowService(): WorkflowService

Raw gRPC access to the Temporal service.

NOTE: The namespace provided in options is not automatically set on requests made via this service object.

Returns​

WorkflowService

Methods​

count()​

count(query?): Promise<CountWorkflowExecution>

Return the number of Workflow Executions matching the given query. If no query is provided, then return the total number of Workflow Executions for this namespace.

Note that the number of Workflow Executions returned is approximate and eventually consistent.

More info on the concept of "visibility" and the query syntax on the Temporal documentation site: https://docs.temporal.io/visibility

Parameters​

query?​

string

Returns​

Promise<CountWorkflowExecution>

execute()​

execute<T>(workflowTypeOrFunc, options): Promise<WorkflowResultType<T>>

Start a new Workflow execution, then await for its completion and return that Workflow's result.

Type Parameters​

T​

T extends Workflow

Parameters​

workflowTypeOrFunc​

string | T

options​

WorkflowStartOptions<T>

Returns​

Promise<WorkflowResultType<T>>

the result of the Workflow execution

executeUpdateWithStart()​

executeUpdateWithStart<T, Ret, Args>(updateDef, updateOptions): Promise<Ret>

Start a new Workflow Execution and immediately send an Update to that Workflow, then await and return the Update's result.

The updateOptions object must contain a WithStartWorkflowOperation, which defines the options for the Workflow execution to start (e.g. the Workflow's type, task queue, input arguments, etc.)

The behavior of Update-with-Start in the case where there is already a running Workflow with the given Workflow ID depends on the specified WorkflowIDConflictPolicy. That is, if the policy is USE_EXISTING, then the Update is issued against the already existing Workflow Execution; however, if the policy is FAIL, then an error is thrown. Caller MUST specify the desired WorkflowIDConflictPolicy.

This call will block until the Update has completed. The Workflow handle can be retrieved by awaiting on WithStartWorkflowOperation.workflowHandle, whether or not the Update succeeds.

Type Parameters​

T​

T extends Workflow

Ret​

Ret

Args​

Args extends any[]

Parameters​

updateDef​

string | UpdateDefinition<Ret, Args, string>

updateOptions​

WorkflowUpdateOptions & object

Returns​

Promise<Ret>

the Update result

getHandle()​

Call Signature​

getHandle<T>(workflowId, runId, options): WorkflowHandle<T>

Create a handle to an existing Workflow.

  • If only workflowId is passed, and there are multiple Workflow Executions with that ID, the handle will refer to the most recent one.
  • If workflowId and runId are passed, the handle will refer to the specific Workflow Execution with that Run ID.
  • If workflowId and GetWorkflowHandleOptions.firstExecutionRunId are passed, the handle will refer to the most recent Workflow Execution in the Chain that started with firstExecutionRunId.

A Chain is a series of Workflow Executions that share the same Workflow ID and are connected by:

This method does not validate workflowId. If there is no Workflow Execution with the given workflowId, handle methods like handle.describe() will throw a WorkflowNotFoundError error.

Type Parameters​
T​

T extends Workflow

Parameters​
workflowId​

string

runId​

string | undefined

options​

WorkflowHandleDefinitionOptions<T>

Returns​

WorkflowHandle<T>

Call Signature​

getHandle<T>(workflowId, runId?, options?): WorkflowHandle<T>

Create a handle to an existing Workflow.

  • If only workflowId is passed, and there are multiple Workflow Executions with that ID, the handle will refer to the most recent one.
  • If workflowId and runId are passed, the handle will refer to the specific Workflow Execution with that Run ID.
  • If workflowId and GetWorkflowHandleOptions.firstExecutionRunId are passed, the handle will refer to the most recent Workflow Execution in the Chain that started with firstExecutionRunId.

A Chain is a series of Workflow Executions that share the same Workflow ID and are connected by:

This method does not validate workflowId. If there is no Workflow Execution with the given workflowId, handle methods like handle.describe() will throw a WorkflowNotFoundError error.

Type Parameters​
T​

T extends Workflow

Parameters​
workflowId​

string

runId?​

string

options?​

GetWorkflowHandleOptions<WorkflowResultType<T>>

Returns​

WorkflowHandle<T>

list()​

list(options?): AsyncWorkflowListIterable

Return a list of Workflow Executions matching the given query.

Note that the list of Workflow Executions returned is approximate and eventually consistent.

More info on the concept of "visibility" and the query syntax on the Temporal documentation site: https://docs.temporal.io/visibility

Parameters​

options?​

ListOptions

Returns​

AsyncWorkflowListIterable

result()​

result<T>(workflowId, runId?, opts?): Promise<WorkflowResultType<T>>

Get the result of a Workflow execution.

Follow the chain of execution in case Workflow continues as new, or has a cron schedule or retry policy.

Type Parameters​

T​

T extends Workflow

Parameters​

workflowId​

string

runId?​

string

opts?​

WorkflowResultOptions<any>

Returns​

Promise<WorkflowResultType<T>>

signalWithStart()​

signalWithStart<WorkflowFn, SignalArgs>(workflowTypeOrFunc, options): Promise<WorkflowHandleWithSignaledRunId<WorkflowFn>>

Start a new Workflow Execution and immediately send a Signal to that Workflow.

The behavior of Signal-with-Start in the case where there is already a running Workflow with the given Workflow ID depends on the WorkflowIDConflictPolicy. That is, if the policy is USE_EXISTING, then the Signal is issued against the already existing Workflow Execution; however, if the policy is FAIL, then an error is thrown. If no policy is specified, Signal-with-Start defaults to USE_EXISTING.

A Signal definition supplies its own TypeInfo. When signaling by name, provide call-site TypeInfo through WorkflowSignalWithStartOptions.signalTypeInfo.

Type Parameters​

WorkflowFn​

WorkflowFn extends Workflow

SignalArgs​

SignalArgs extends any[] = []

Parameters​

workflowTypeOrFunc​

string | WorkflowFn

options​

WithWorkflowArgs<WorkflowFn, WorkflowSignalWithStartOptions<SignalArgs>>

Returns​

Promise<WorkflowHandleWithSignaledRunId<WorkflowFn>>

a WorkflowHandle to the started Workflow

start()​

start<T>(workflowTypeOrFunc, options): Promise<WorkflowHandleWithStartDetails<T>>

Start a new Workflow execution.

Type Parameters​

T​

T extends Workflow

Parameters​

workflowTypeOrFunc​

string | T

options​

WorkflowStartOptions<T>

Returns​

Promise<WorkflowHandleWithStartDetails<T>>

a WorkflowHandle to the started Workflow

startUpdateWithStart()​

startUpdateWithStart<T, Ret, Args>(updateDef, updateOptions): Promise<WorkflowUpdateHandle<Ret>>

Start a new Workflow Execution and immediately send an Update to that Workflow, then return a WorkflowUpdateHandle for that Update.

The updateOptions object must contain a WithStartWorkflowOperation, which defines the options for the Workflow execution to start (e.g. the Workflow's type, task queue, input arguments, etc.)

The behavior of Update-with-Start in the case where there is already a running Workflow with the given Workflow ID depends on the specified WorkflowIDConflictPolicy. That is, if the policy is USE_EXISTING, then the Update is issued against the already existing Workflow Execution; however, if the policy is FAIL, then an error is thrown. Caller MUST specify the desired WorkflowIDConflictPolicy.

This call will block until the Update has reached the specified WorkflowUpdateStage. Note that this means that the call will not return successfully until the Update has been delivered to a Worker. The Workflow handle can be retrieved by awaiting on WithStartWorkflowOperation.workflowHandle, whether or not the Update succeeds.

Type Parameters​

T​

T extends Workflow

Ret​

Ret

Args​

Args extends any[]

Parameters​

updateDef​

string | UpdateDefinition<Ret, Args, string>

updateOptions​

WorkflowUpdateOptions & object

Returns​

Promise<WorkflowUpdateHandle<Ret>>

a WorkflowUpdateHandle to the started Update

withAbortSignal()​

withAbortSignal<R>(abortSignal, fn): Promise<R>

Set an AbortSignal that, when aborted, cancels any ongoing service requests executed in fn's scope. This will locally result in the request call throwing a _grpc.ServiceError|ServiceError with code _grpc.status.CANCELLED|CANCELLED; see isGrpcCancelledError.

This method is only a convenience wrapper around Connection.withAbortSignal.

Type Parameters​

R​

R

Parameters​

abortSignal​

AbortSignal

fn​

() => Promise<R>

Returns​

Promise<R>

value returned from fn

See​

https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal

Inherited from​

BaseClient.withAbortSignal

withDeadline()​

withDeadline<R>(deadline, fn): Promise<R>

Set a deadline for any service requests executed in fn's scope.

The deadline is a point in time after which any pending gRPC request will be considered as failed; this will locally result in the request call throwing a _grpc.ServiceError|ServiceError with code _grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED; see isGrpcDeadlineError.

It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is possible for the client to end up waiting forever for a response.

This method is only a convenience wrapper around Connection.withDeadline.

Type Parameters​

R​

R

Parameters​

deadline​

number | Date

a point in time after which the request will be considered as failed; either a Date object, or a number of milliseconds since the Unix epoch (UTC).

fn​

() => Promise<R>

Returns​

Promise<R>

the value returned from fn

See​

https://grpc.io/docs/guides/deadlines/

Inherited from​

BaseClient.withDeadline

withMetadata()​

withMetadata<R>(metadata, fn): Promise<R>

Set metadata for any service requests executed in fn's scope.

This method is only a convenience wrapper around Connection.withMetadata.

Type Parameters​

R​

R

Parameters​

metadata​

Metadata

fn​

() => Promise<R>

Returns​

Promise<R>

returned value of fn

Inherited from​

BaseClient.withMetadata