Skip to main content

Interface: WorkflowContext

The context of a tier-2 workflow function.

Properties​

cancellationScope​

readonly cancellationScope: CancellationScopeFunction

Run fn in a new cancellation scope. fn gets a ctx bound to the scope: use it inside fn. This outer ctx joins the scope only while fn runs synchronously; after an await it is back in its own scope, so concurrent branches never share a scope by accident.


info​

readonly info: WorkflowInfo


log​

readonly log: WorkflowLogger


sinks​

readonly sinks: WorkflowSinks

Worker-side sinks (self-hosted workers).

Methods​

activity()​

activity<In, Out>(activity, options): Promise<Out>

Run a user activity on a self-hosted worker ( SCHEDULE_ACTIVITY of kind user). Needs fluidgrids.self-hosted-workers; the managed queue refuses user activities.

Type Parameters​

In​

In

Out​

Out

Parameters​

activity​

string | ActivityDefinition<In, Out>

options​

ActivityOptions<In>

Returns​

Promise<Out>


allHandlersFinished()​

allHandlersFinished(): Promise<void>

Resolves when no asynchronous signal or update handler is running; cancellation does not interrupt the wait.

Returns​

Promise<void>


cancelRun()​

cancelRun(target): Promise<void>

Shorthand for getRunHandle(target).cancel().

Parameters​

target​

ExternalRunTarget

Returns​

Promise<void>


child()​

child<Out>(target, options?): Promise<Out>

Start a child run and wait for its result.

Type Parameters​

Out​

Out = Json

Parameters​

target​

ChildTarget<Out>

options?​

ChildOptions

Returns​

Promise<Out>


condition()​

condition(predicate, timeout?): Promise<boolean>

Resolves true once predicate holds after an event, or false when timeout passes first.

Parameters​

predicate​

() => boolean

timeout?​

Duration

Returns​

Promise<boolean>


continueAsNew()​

continueAsNew(input, options?): Promise<never>

End this run and start a fresh history (parity command CONTINUE_AS_NEW).

Parameters​

input​

unknown

options?​

ContinueAsNewOptions

Returns​

Promise<never>


deprecatePatch()​

deprecatePatch(patchId): void

Parameters​

patchId​

string

Returns​

void


getRunHandle()​

getRunHandle(target): ExternalRunHandle

Parameters​

target​

ExternalRunTarget

Returns​

ExternalRunHandle


handleQuery()​

handleQuery<Result, Args>(query, handler): void

Answer a custom query: handler runs after the history is replayed and must return a value without changing the run (commands and sinks throw QueryHandlerSideEffect).

Type Parameters​

Result​

Result

Args​

Args

Parameters​

query​

string | QueryDefinition<Result, Args>

handler​

(args) => Result

Returns​

void


handleUpdate()​

handleUpdate<Args, Result>(update, handler, options?): void

Handle an update (05 §6): validate may reject it (no history), the handler's result or failure completes it (UPDATE_COMPLETED). The handler may await activities, timers and children.

Type Parameters​

Args​

Args

Result​

Result

Parameters​

update​

string | UpdateDefinition<Args, Result>

handler​

(args) => Result | Promise<Result>

options?​

UpdateHandlerOptions<Args>

Returns​

void


isCancellation()​

isCancellation(error): boolean

Parameters​

error​

unknown

Returns​

boolean


localActivity()​

Call Signature​

localActivity<In, Out>(operation, options): Promise<Out>

Run a short, idempotent call inside the workflow task (11 §2.12): the worker that runs the task executes it and the task records one LOCAL_ACTIVITY_COMPLETED or LOCAL_ACTIVITY_FAILED marker (RECORD_LOCAL_ACTIVITY). Replays return the recorded outcome and never run it again. Local activities run at least once, so the call must be idempotent.

  • A node operation runs on a managed worker; the activity allow-list of ctx.run applies.
  • A user activity (a declareActivity() value or its name, gap G5) runs in the process of the self-hosted worker that runs the task, from the implementations in its activities. The workflow must run on a self-hosted task queue; on managed the call throws a non-retryable taskQueue.userActivityOnManaged error. The declaration's task queue does not apply: a local activity always runs on the task's worker.
Type Parameters​
In​

In

Out​

Out

Parameters​
operation​

Operation<In, Out>

options​

LocalActivityOptions<In>

Returns​

Promise<Out>

Call Signature​

localActivity<In, Out>(activity, options): Promise<Out>

Type Parameters​
In​

In

Out​

Out

Parameters​
activity​

string | ActivityDefinition<In, Out>

options​

UserLocalActivityOptions<In>

Returns​

Promise<Out>


nonCancellable()​

nonCancellable<T>(fn): Promise<T>

cancellationScope(fn, { nonCancellable: true }); the same ctx rule applies.

Type Parameters​

T​

T

Parameters​

fn​

(ctx) => Promise<T>

Returns​

Promise<T>


now()​

now(): number

The workflow clock (the task's start time), in epoch milliseconds.

Returns​

number


onCancel()​

onCancel(fn): void

Run fn when the current scope is cancelled. An error thrown by fn is handled like an error thrown by the workflow; the other handlers still run.

Parameters​

fn​

() => void

Returns​

void


onSignal()​

Call Signature​

onSignal<P>(signal, handler): void

Handle every signal of this name, buffered ones first.

Type Parameters​
P​

P

Parameters​
signal​

string | SignalDefinition<P>

handler​

(payload) => unknown

Returns​

void

Call Signature​

onSignal<P>(signal, options, handler): void

Type Parameters​
P​

P

Parameters​
signal​

string | SignalDefinition<P>

options​

SignalHandlerOptions

handler​

(payload) => unknown

Returns​

void


patched()​

patched(patchId): boolean

In-place versioning (spec 06 §4).

Parameters​

patchId​

string

Returns​

boolean


random()​

random(): number

A deterministic random number in [0, 1), seeded per run.

Returns​

number


run()​

run<In, Out>(operation, options): Promise<Out>

Run a canvas node operation as a durable activity (SCHEDULE_ACTIVITY, kind node).

Type Parameters​

In​

In

Out​

Out

Parameters​

operation​

Operation<In, Out>

options​

RunOptions<In>

Returns​

Promise<Out>


saga()​

saga(): Saga

Returns​

Saga


setCurrentDetails()​

setCurrentDetails(markdown): void

Live Markdown status for the run page and __metadata (at most 20 KiB).

Parameters​

markdown​

string

Returns​

void


setDefaultQueryHandler()​

setDefaultQueryHandler(handler): void

Answer queries no handler takes.

Parameters​

handler​

(name, args) => unknown

Returns​

void


setDefaultSignalHandler()​

setDefaultSignalHandler(handler): void

Handle signals no other handler or waiter takes.

Parameters​

handler​

(name, payload) => unknown

Returns​

void


setDefaultUpdateHandler()​

Call Signature​

setDefaultUpdateHandler(handler, options?): void

Handle updates no handler takes (11 §2.29).

Parameters​
handler​

(name, args) => unknown

options?​

DefaultUpdateHandlerOptions

Returns​

void

Call Signature​

setDefaultUpdateHandler(options, handler): void

Parameters​
options​

DefaultUpdateHandlerOptions

handler​

(name, args) => unknown

Returns​

void


sideEffect()​

sideEffect<T>(fn): T

Record a value once (RECORD_SIDE_EFFECT); replays return the recorded value.

Type Parameters​

T​

T extends Json

Parameters​

fn​

() => T

Returns​

T


signalParent()​

signalParent<P>(signal, payload?): Promise<void>

Signal the parent run.

Type Parameters​

P​

P

Parameters​

signal​

string | SignalDefinition<P>

payload?​

P

Returns​

Promise<void>


signalReceived()​

signalReceived<P>(signal): Promise<P>

The next signal of this name (buffered signals first).

Type Parameters​

P​

P

Parameters​

signal​

string | SignalDefinition<P>

Returns​

Promise<P>


signalRun()​

signalRun<P>(target, signal, payload?): Promise<void>

Signal another run of the workspace (by run id or workflow id); resolves on delivery.

Type Parameters​

P​

P

Parameters​

target​

ExternalRunTarget

signal​

string | SignalDefinition<P>

payload?​

P

Returns​

Promise<void>


sleep()​

sleep(duration, options?): Promise<void>

A durable timer.

Parameters​

duration​

Duration

options?​
summary?​

string

Returns​

Promise<void>


startChild()​

startChild<Out>(target, options?): Promise<ChildHandle<Out>>

Start a child run; resolves once it has started.

Type Parameters​

Out​

Out = Json

Parameters​

target​

ChildTarget<Out>

options?​

ChildOptions

Returns​

Promise<ChildHandle<Out>>


upsertContext()​

upsertContext(entries): void

Merge keys into the run's context (parity command UPSERT_CONTEXT).

Parameters​

entries​

JsonObject

Returns​

void


upsertSearchAttributes()​

upsertSearchAttributes(attributes): void

Upsert the run's search attributes (11 §2.8, UPSERT_SEARCH_ATTRIBUTES); a null value removes one. The service validates the values against the workspace definitions.

Parameters​

attributes​

JsonObject

Returns​

void


uuid()​

uuid(): string

A deterministic version-4 UUID.

Returns​

string