WorkflowService

the instance waiting

task

the wait

Returns

Promise<boolean>

true when allowed

childLauncher()

protected childLauncher(def, launcher, input): Promise<WorkflowLauncher>

Defined in: packages/workflow/src/workflow.service.ts:829

Identity of a child flow, which must be allowed to call the flow operation like a launch

Parameters

def

the child flow

launcher

the launcher of the parent

input

any

the child input

Returns

Promise<WorkflowLauncher>

the launcher of the child

Throws

TaskError Forbidden when the child may not be started

claim()

protected claim(task, extra?): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1188

Claim a task with a lease: a conditional patch on its leaseUntil

Reclaiming an expired lease counts as a new attempt.

Parameters

task

the task, as queried

extra?

Partial<WorkflowTask> = {}

other fields to set with the claim

Returns

Promise<boolean>

true when this worker holds the task

claimDue()

protected claimDue(): Promise<WorkflowTask[]>

Defined in: packages/workflow/src/workflow.service.ts:1158

Claim the due tasks, up to the free slots of this replica

The PENDING tasks due now, and the RUNNING ones whose lease expired (their worker crashed)

Returns

Promise<WorkflowTask[]>

the tasks claimed

computeParameters()

computeParameters(): void

Defined in: packages/core/lib/services/service.d.ts:77

Used to compute or derivate input parameter to attribute

Returns

void

Deprecated

Inherited from

Service.computeParameters

consumeBuffered()

protected consumeBuffered(instance, task): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1934

Resolve a new wait with the oldest unexpired buffered signal its instance accepts

Parameters

instance

the instance

task

the wait

Returns

Promise<boolean>

true when a signal was consumed

consumeSignal()

protected consumeSignal(signal, instance, task, advance): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1954

Consume a buffered signal for a wait: its sender is checked now, against this instance

Parameters

signal

WorkflowSignal

the buffered signal

instance

the instance waiting

task

the wait

advance

boolean

advance the instance once the payload is journaled

Returns

Promise<boolean>

true when consumed and delivered

createInstance()

protected createInstance(def, input, launcher, options?): Promise<WorkflowInstance>

Defined in: packages/workflow/src/workflow.service.ts:1036

Create an instance and run it to its first tasks

Parameters

def

the flow definition, pinned in the instance

input

Record<string, any>

the flow input

launcher

the identity of the steps

options?

the parent of an awaited child, a fixed uuid (created once)

parent?

{ instance: string; key: string; }

parent instance and task key

parent.instance

string

parent instance uuid

parent.key

string

task key in the parent

uuid?

string

uuid of the instance: an existing one is not created again

Returns

Promise<WorkflowInstance>

the instance

createTask()

protected createTask(instance, scheduled, launcherId, runAt, attempt, index?, extra?): Promise<WorkflowTask | undefined>

Defined in: packages/workflow/src/workflow.service.ts:2030

Create a task row, unless another worker created the same row first

Parameters

instance

string

the instance uuid

scheduled

ScheduledTask

the task

launcherId

string | undefined

user id of the launcher

runAt

number

when it becomes runnable

attempt

number

attempt number

index?

number

row index of the key, when known

extra?

Partial<WorkflowTask> = {}

other fields of the row

Returns

Promise<WorkflowTask | undefined>

the task created, undefined when another worker created it

deliverBuffered()

protected deliverBuffered(signal): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1919

Deliver a just buffered signal to a wait created while it was being saved

Parameters

signal

WorkflowSignal

the buffered signal

Returns

Promise<boolean>

true when a wait consumed it

deliverToParent()

protected deliverToParent(childId): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1642

Journal the end of a child into its parent: its output, its error, or Cancelled

Parameters

childId

string

the child instance uuid

Returns

Promise<void>

emit()

emit<Key>(event, data): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:213

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters

Key

Key extends never

Parameters

event

Key

the event name

data

object[Key]

the data to process

Returns

Promise<void>

Inherited from

Service.emit

execute()

protected execute(task, advance?): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1226

Run a claimed task, write its outcome and advance its instance

Every write of the attempt is conditional on the lease this worker holds: an attempt whose lease was lost (its worker was too slow and another one reclaimed it) drops its outcome.

Parameters

task

the task

advance?

boolean = true

advance the instance after the outcome is journaled

Returns

Promise<void>

finishTask()

protected finishTask(task, data): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1337

Record the end of an attempt, if this worker still holds its lease

leaseUntil becomes the end time, never 0: a worker that queried the task before cannot claim it again.

Parameters

task

WorkflowControls.getStoredWorkflowRole

the task

data

Partial<WorkflowTask>

status and outcome

Returns

Promise<boolean>

false when the lease was lost

getCapabilities()

getCapabilities(): Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:72

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns

Record<string, any>

the result

Webda Capability-tagged

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
  const caps = super.getCapabilities();
  if (!this.parameters.enabled) delete caps["request-filter"];
  return caps;
}

Inherited from

Service.getCapabilities

getClientEvents()

getClientEvents(): string[]

Defined in: packages/core/lib/services/service.d.ts:144

Return the events that an external system can subscribe to

Returns

string[]

the list of results

Inherited from

Service.getClientEvents

getFlow()

getFlow(flowId): FlowDefinition | undefined

Defined in: packages/workflow/src/workflow.service.ts:624

Get a registered flow

Parameters

flowId

string

the flow id

Returns

FlowDefinition | undefined

the definition

getFlowVersion()

getFlowVersion(flowId, version): FlowDefinition | undefined

Defined in: packages/workflow/src/workflow.service.ts:649

Find a version of a flow

Parameters

flowId

string

the flow id

version

string

the version

Returns

FlowDefinition | undefined

the definition

getMaxListeners()

getMaxListeners(): number

Defined in: packages/core/lib/events/asynceventemitter.d.ts:91

Returns

number

Inherited from

Service.getMaxListeners

getMetric()

getMetric<T>(type, configuration): T

Defined in: packages/core/lib/services/service.d.ts:138

Add service name label

Type Parameters

T

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters

type

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration

MetricConfiguration<T>

the configuration

Returns

T

the result

Inherited from

Service.getMetric

getName()

getName(): string

Defined in: packages/core/lib/services/service.d.ts:218

Get service name

Returns

string

the result string

Inherited from

Service.getName

getOpenApiReplacements()

getOpenApiReplacements(): any

Defined in: packages/core/lib/services/service.d.ts:182

Return variables for replacement in openapi

Returns

any

the result

Inherited from

Service.getOpenApiReplacements

getOperationId()

getOperationId(id): string | undefined

Defined in: packages/core/lib/services/service.d.ts:167

If undefined is returned it cancel the operation registration

Parameters

id

string

the identifier

Returns

string | undefined

the result

Inherited from

Service.getOperationId

getParameters()

getParameters(): T

Defined in: packages/core/lib/services/service.d.ts:82

Get the service parameters

Returns

T

the result

Inherited from

Service.getParameters

getService()

getService<T>(name): ServicesMap[T]

Defined in: packages/core/lib/services/service.d.ts:131

Get a service by name

Type Parameters

T

T extends keyof ServicesMap

Parameters

name

T

the name to use

Returns

ServicesMap[T]

the result map

Deprecated

Use useService, might reconsider

Inherited from

Service.getService

getState()

getState(): ServiceStates

Defined in: packages/core/lib/services/service.d.ts:55

Get the current state

Returns

ServiceStates

the result

Inherited from

Service.getState

getStoredWorkflowRole()

getStoredWorkflowRole(): string

Defined in: packages/workflow/src/workflow.service.ts:663

Role needed to write a stored workflow

Returns

string

the role

Implementation of

getUrl()

getUrl(url, _methods): string

Defined in: packages/core/lib/services/service.d.ts:161

Return the full path url based on parameters

Parameters

url

string

relative url to service

_methods

HttpMethodType[]

in case we need filtering (like Store)

Returns

string

absolute url or undefined if need to skip the Route

Inherited from

Service.getUrl

holdsLease()

protected holdsLease(task): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1309

Check this worker still holds the lease of a task, and extend it

Parameters

task

the task

Returns

Promise<boolean>

false when the lease was lost

init()

init(): Promise<WorkflowService<T>>

Defined in: packages/workflow/src/workflow.service.ts:528

Returns

Promise<WorkflowService<T>>

Overrides

Service.init

initMetrics()

initMetrics(): void

Defined in: packages/core/lib/services/service.d.ts:124

Init the metrics

Returns

void

Inherited from

Service.initMetrics

initOperations()

initOperations(): void

Defined in: packages/core/lib/services/service.d.ts:195

Init the operations from

Returns

void

Operation

decorators on this service

Inherited from

Service.initOperations

instanceLauncher()

protected instanceLauncher(def, launcher): WorkflowLauncher

Defined in: packages/workflow/src/workflow.service.ts:812

Identity of a new instance: a stored flow never runs as the system, it runs as its last saver

Parameters

def

the flow

launcher

the identity of the caller (launch) or of the parent instance (child flows)

Returns

the launcher of the instance

Throws

Forbidden when a stored flow launched by the system has no user to run as

launch()

launch(...args): Promise<{ uuid: string; }>

Defined in: packages/workflow/src/workflow.service.ts:996

Launch the flow of the current operation, as the caller

Parameters

args

...any[]

the flow parameters, in order

Returns

Promise<{ uuid: string; }>

the instance uuid

launcherContext()

protected launcherContext(launcher, input): SimpleOperationContext

Defined in: packages/workflow/src/workflow.service.ts:1440

Build the context of the launcher: the session is rebuilt from the user id, so the permissions are fresh

Parameters

launcher

WorkflowControls.migrateInstance

the launcher

input

any

the operation input

Returns

SimpleOperationContext

the context

listeners()

listeners(eventName): Function[]

Defined in: packages/core/lib/events/asynceventemitter.d.ts:151

Get all listeners for an event

Parameters

eventName

never

the event name

Returns

Function[]

the list of results

Inherited from

Service.listeners

listenStored()

protected listenStored(): void

Defined in: packages/workflow/src/workflow.service.ts:670

Validate and stamp stored workflows on save, and register them once saved

Returns

void

loadCapabilities()

protected loadCapabilities(): void

Defined in: packages/core/lib/services/service.d.ts:120

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns

void

Example

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See

getCapabilities

Inherited from

Service.loadCapabilities

log()

log(level, ...args): void

Defined in: packages/core/lib/services/service.d.ts:236

Log operation

Parameters

level

WorkerLogLevel

to log

args

...any[]

additional arguments

Returns

void

Inherited from

Service.log

maybeSweep()

protected maybeSweep(): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1100

Run the recovery sweep when sweepInterval passed since the last one

Returns

Promise<void>

migrateInstance()

migrateInstance(uuid, version?): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1765

Move a running instance to another version of its flow

Refused when a journaled or live task key has no statement in the target graph.

Parameters

uuid

string

the instance uuid

version?

string

the target version, the latest registered when undefined

Returns

Promise<void>

Implementation of

off()

off<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:127

Perform off

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.off

Inherited from

Service.off

on()

on<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:111

Perform on

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.on

once()

once<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:103

Perform once

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.once

operationFlow()

protected operationFlow(flowId): FlowDefinition | undefined

Defined in: packages/workflow/src/workflow.service.ts:783

The flow served by an operation, if it is a flow

Parameters

flowId

string

the operation id

Returns

FlowDefinition | undefined

the flow of the WorkflowService serving the operation

operationSchemaName()

protected operationSchemaName(method, side): string

Defined in: packages/core/lib/services/service.d.ts:191

Schema of an operation side: <service name>.<method>.<side> when the application knows it, else the one the build writes, <class>.<method>.<side>, for the class or its nearest ancestor that has it (a service configured under another name than its class)

Parameters

method

string

the method name

side

"input" | "output"

input or output

Returns

string

the schema name

Inherited from

Service.operationSchemaName

patchInstance()

protected patchInstance(instance, data): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1514

Patch an instance if its revision did not change

Parameters

instance

the instance as read

data

Partial<WorkflowInstance>

the changes

Returns

Promise<boolean>

false when another writer changed it first

patchLeased()

protected patchLeased(task, data): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1290

Conditional patch of a task row on the lease this worker holds

Parameters

task

the task, with the lease this worker holds

data

Partial<WorkflowTask>

the changes

Returns

Promise<boolean>

false when another worker holds the lease now

poll()

protected poll(): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1077

One iteration of the worker loop: claim due tasks and run them in the background

Returns

Promise<void>

the poll in progress, it ends when the tasks are claimed and started

prepareStored()

protected prepareStored(workflow, target): void

Defined in: packages/workflow/src/workflow.service.ts:692

Validate a stored workflow about to be saved and stamp its version and last saver

Parameters

workflow

any

the workflow as it will be saved

target

any

the data written: receives version and updatedBy

Returns

void

registerFlow()

registerFlow(def): void

Defined in: packages/workflow/src/workflow.service.ts:589

Parameters

def

the flow definition

Returns

void

registerModuleFlows()

protected registerModuleFlows(): void

Defined in: packages/workflow/src/workflow.service.ts:413

The first WorkflowService to resolve registers them; the typed calls are resolved in init, once every service registered its operations.

Returns

void

registerSchema()

protected registerSchema(name, schema): void

Defined in: packages/workflow/src/workflow.service.ts:578

Parameters

name

string

schema name

schema

any

the JSON schema

Returns

void

registerStored()

protected registerStored(workflow): boolean

Defined in: packages/workflow/src/workflow.service.ts:878

Validate then register a stored workflow; an invalid one is removed and logged

Parameters

workflow

StoredWorkflow

the stored workflow

Returns

boolean

true when registered

reloadStored()

protected reloadStored(): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:957

Load every stored workflow: register the new and changed ones, remove the deleted ones

Returns

Promise<void>

removeAllListeners()

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:134

Remove all listeners

Type Parameters

Key

Key extends never

Parameters

eventName?

Key

the event name

Returns

this

this for chaining

See

EventEmitter.removeAllListeners

Inherited from

Service.removeAllListeners

removeListener()

removeListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:119

Remove listener

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.removeListener

Inherited from

Service.removeListener

renewLease()

protected renewLease(task): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1317

Extend the lease of a running task, abort the attempt when the lease was lost

Parameters

task

the task

Returns

Promise<void>

resolve()

resolve(): this

Defined in: packages/workflow/src/workflow.service.ts:395

Returns

this

Overrides

Service.resolve

resolveFlow()

resolveFlow(flowId): FlowDefinition | undefined

Defined in: packages/workflow/src/workflow.service.ts:633

Find a flow registered on any WorkflowService, by its operation

Parameters

flowId

string | undefined

the flow id

Returns

FlowDefinition | undefined

the current definition, undefined when the operation is not a flow

resolveModuleTargets()

protected resolveModuleTargets(): void

Defined in: packages/workflow/src/workflow.service.ts:490

Point every typed call of the compiled flows at the operation of the configured service of its class

A flow whose service is not configured (a packaged unit without it) is removed with its crons; a call that several services serve, or a flow whose operation was taken over, stops the startup.

Returns

void

Throws

FatalInitError on an ambiguous call, or a flow id taken by another operation

resolveTarget()

resolveTarget(target): object

Defined in: packages/workflow/src/workflow.service.ts:441

The operation a typed call (target: { class, method }) runs: the operation of the configured service whose instance is of that class (matched by constructor name, the class or an ancestor)

Parameters

target

the target of the task

class

string

the service class name

method

string

the method name

Returns

object

the operation id, or why there is none: no service (missing) or several (ambiguous)

ambiguous?

optional ambiguous?: string

missing?

optional missing?: string

operation?

optional operation?: string

resolveTargets()

protected resolveTargets(body): object

Defined in: packages/workflow/src/workflow.service.ts:466

Resolve the typed calls of a flow body in place

Parameters

body

any[]

the statements

Returns

object

the problems, by statement id

ambiguous

ambiguous: string[]

missing

missing: string[]

resolveWait()

protected resolveWait(task, payload, advance?): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1995

Resolve a wait with a payload: claimed like a task, so it resolves once

Parameters

task

WorkflowControls.retryInstance

the wait

payload

any

its result

advance?

boolean = true

advance the instance once the payload is journaled

Returns

Promise<boolean>

false when the wait was already resolved or timed out

retryInstance()

retryInstance(uuid): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1727

Restart a failed instance: drop the outcome that failed it and every outcome journaled after it, then replay

Parameters

uuid

string

the instance uuid

Returns

Promise<void>

Implementation of

runTask()

protected runTask(task, instance, controller): Promise<any>

Defined in: packages/workflow/src/workflow.service.ts:1365

Run the operation (or built-in) of a task

Parameters

task

the task

instance

its instance

controller

AbortController

aborted on timeout

Returns

Promise<any>

the result

scheduleChild()

protected scheduleChild(instance, scheduled, index): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1611

Start an awaited child flow: the task waits for the child instance, which runs as the same launcher

Parameters

instance

the parent instance

scheduled

ScheduledTask

the task, its operation is a flow id

index

number

row index of the key

Returns

Promise<boolean>

true when the child finished at once: the parent journal changed

scheduleRetry()

protected scheduleRetry(task): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1346

Create the next attempt of a failed task, after the backoff delay

Parameters

task

the failed attempt

Returns

Promise<void>

scheduleTask()

protected scheduleTask(instance, scheduled): Promise<boolean>

Defined in: packages/workflow/src/workflow.service.ts:1570

Create the task of a scheduled key, unless a PENDING or RUNNING one exists

Parameters

instance

the instance

scheduled

ScheduledTask

the task to run

Returns

Promise<boolean>

true when the task was resolved at once (a buffered signal): the journal changed

setMaxListeners()

setMaxListeners(n): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:95

Parameters

n

number

Returns

this

Inherited from

Service.setMaxListeners

signal()

signal(event, key, payload?): Promise<{ delivered: number; }>

Defined in: packages/workflow/src/workflow.service.ts:1806

Deliver a signal: resolve the waits on (event, key) whose instance accepts the caller, or buffer it when nothing waits

Parameters

event

string

event name

key

string

business key

payload?

any

the result of the waits

Returns

Promise<{ delivered: number; }>

the number of waits resolved

sleepUntil()

protected sleepUntil(input, now): number

Defined in: packages/workflow/src/workflow.service.ts:2007

End of a Workflow.Sleep

Parameters

input

any

{ duration?: string, until?: number }

now

number

the current time

Returns

number

when the timer fires

startSync()

protected startSync(): void

Defined in: packages/workflow/src/workflow.service.ts:977

Follow the stored workflow changes of the other replicas: through syncPubSub, or a reload every syncInterval

Returns

void

startWorker()

protected startWorker(): void

Defined in: packages/workflow/src/workflow.service.ts:1067

Start the worker loop

Returns

void

stop()

stop(): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:547

Stop the worker loop

Running attempts get stopTimeout to finish, then they are aborted and their outcome dropped: their lease expires and another worker runs them again.

Returns

Promise<void>

Overrides

Service.stop

storedChanged()

protected storedChanged(uuid): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:851

A stored workflow changed on this replica: register it here and tell the others

Parameters

uuid

string

the workflow uuid

Returns

Promise<void>

storedRunAs()

storedRunAs(flowId): string | undefined

Defined in: packages/workflow/src/workflow.service.ts:795

User a stored flow runs as when the system launches it: its last saver

Parameters

flowId

string

the flow id

Returns

string | undefined

the user id, undefined when unknown

supersede()

protected supersede(row): Promise<void>

Defined in: packages/workflow/src/workflow.service.ts:1712

Mark a task row CANCELLED, conditionally on its lease: whoever holds it can no longer write its outcome

Parameters

row