Skip to content

Process

A Process Business Object describes a BPMN process. In code, each Process is a class with static methods under This.$Process.<ProcessName>: they start Process instances and, on the server, signal, message, read, update or end running ones.

Availability: Both¹

This.$Process.<ProcessName>

Processes are grouped under the $Process namespace. This.<ProcessName> does not work; the $Process. part is required.

Processes are typed only for server-side and client-side code. Shared code (Entity methods with availability serverAndClient or calculation) cannot reference them.

In the signatures below, <ProcessName> stands for the Process’s name and <StartByUnion> for the start options generated from the Process’s start events (see startBy).

start(inputData: <ProcessName>.ProcessInputData, startBy?: <StartByUnion>): Promise<number>

Starts a new Process instance with the given input data and returns its id. The current End user becomes the instance’s initiator.

ParameterTypeDescription
inputData<ProcessName>.ProcessInputDataValues for the Process’s input variables.
startBy<StartByUnion>Which start event to use. Optional when the Process has a plain start event, required otherwise.

Returns: Promise<number>, the id of the new Process instance · Availability: Both¹

// the keys of inputData are the input variables defined on the Process
const instanceId = await This.$Process.PurchaseRequest.start({
request: myRequest,
})

On the client, the access control rule checked is the Process’s start item, which receives inputData.

startAndGetFirstUserTaskToken(inputData: <ProcessName>.ProcessInputData, startBy?: <StartByUnion>, taskTimeoutMs?: number, taskDebounceMs?: number): Promise<{ instanceId: number, taskToken: Sys.Types.UserTaskToken }>

Starts a new Process instance and waits for the first user task that the current End user may work on.

ParameterTypeDescription
inputData<ProcessName>.ProcessInputDataValues for the Process’s input variables.
startBy<StartByUnion>Which start event to use. Optional when the Process has a plain start event, required otherwise.
taskTimeoutMsnumberHow long to wait for a user task, in milliseconds. Default 1500.
taskDebounceMsnumberHow long to wait after a user task appears for further ones, in milliseconds, before picking the one with the highest priority. Default 100.

Returns: Promise<{ instanceId: number, taskToken: Sys.Types.UserTaskToken }>. taskToken is undefined when no user task for the current End user appears within the timeout · Availability: Both¹

On the client, the access control rule checked is the Process’s start item, as for start().

startAndNavigateToFirstUserTask(inputData: <ProcessName>.ProcessInputData, isNewWindow: boolean | string, startBy?: <StartByUnion>, failIfNoUserTask?: boolean, taskTimeoutMs?: number, taskDebounceMs?: number): Promise<{ instanceId: number, taskToken: Sys.Types.UserTaskToken }>

Starts a new Process instance, waits for the first user task of the current End user, and opens that task’s screen.

ParameterTypeDescription
inputData<ProcessName>.ProcessInputDataValues for the Process’s input variables.
isNewWindowboolean | stringfalse opens the task in the current window. true opens a new window; a string opens the window with that name.
startBy<StartByUnion>Which start event to use. Optional when the Process has a plain start event, required otherwise.
failIfNoUserTaskbooleanThrow an error when no user task appears within the timeout. Default true.
taskTimeoutMsnumberHow long to wait for a user task, in milliseconds. Default 1500.
taskDebounceMsnumberHow long to wait after a user task appears for further ones, in milliseconds. Default 100.

Returns: Promise<{ instanceId: number, taskToken: Sys.Types.UserTaskToken }> · Availability: Client

The Process instance is started through startAndGetFirstUserTaskToken(), so the same access control rule applies.

terminateProcessInstance(processInstanceId: number): Promise<void>

Stops a Process instance and deletes its tokens, lane assignments and process data. Open Step executions are recorded as cancelled. The Process instance record itself is kept, and its status is not changed.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.

Returns: Promise<void> · Availability: Server

cancelProcessInstance(processInstanceId: number): Promise<void>

Terminates a running or suspended Process instance and sets its status to terminated. Throws an error if the Process instance has already completed or been terminated.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.

Returns: Promise<void> · Availability: Server

deleteProcessInstance(processInstanceId: number): Promise<void>

Terminates a Process instance, then deletes it together with its recorded Step executions.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.

Returns: Promise<void> · Availability: Server

sendSignal(processInstanceId: number, signalName: <SignalName>): Promise<void>

Sends a BPMN signal to a running Process instance. <SignalName> is the union of the signal names used in the Process, or never if it uses none. Throws an error if the Process instance is not found or the Process has no signal with that name.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.
signalName<SignalName>Name of the signal.

Returns: Promise<void> · Availability: Server

sendMessage(processInstanceId: number, messageName: '<MessageName>', messageData: <MessageDataType>): Promise<void>

Sends a BPMN message with data to a running Process instance. There is one overload per message used in the Process, each with that message’s name and data type. A Process without messages gets a single overload whose parameters are never. Throws an error if the Process instance is not found or the Process has no message with that name.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.
messageName'<MessageName>'Name of the message.
messageData<MessageDataType>Data sent with the message, of the type defined on the message.

Returns: Promise<void> · Availability: Server

getRootData(processInstanceId: number): Promise<Sys.Types.ProcessScope<<ProcessName>.ProcessData>>

Reads the root data of a Process instance: its process variables, its initiator and how it was started.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.

Returns: Promise<Sys.Types.ProcessScope<<ProcessName>.ProcessData>> · Availability: Server

updateRootData(processInstanceId: number, updateData: Partial<Sys.Types.ProcessScope<<ProcessName>.ProcessData>>): Promise<void>
updateRootData<T>(processInstanceId: number, updateFn: ((data: Sys.Types.ProcessScope<<ProcessName>.ProcessData>) => (T | Promise<T>))): Promise<T>

Changes the root data of a Process instance under a lock and saves it.

ParameterTypeDescription
processInstanceIdnumberId of the Process instance.
updateDataPartial<Sys.Types.ProcessScope<<ProcessName>.ProcessData>>Top-level keys to replace. Passing process replaces the whole process data object, not single variables.
updateFn(data) => T | Promise<T>Function that changes data in place. Its return value is passed on as the result.

Returns: Promise<void> for updateData, Promise<T> for updateFn · Availability: Server

// change one process variable and keep the others
await This.$Process.PurchaseRequest.updateRootData(instanceId, (data) => {
data.process.isUrgent = true
})

The values accepted by the startBy parameter are generated from the Process’s start events, as a union of:

ValueWhen it is included
'normal'The Process has a plain start event.
{ signalName: '<SignalName>' }The Process has signal start events. <SignalName> is the union of their signal names.
{ messageName: '<MessageName>', messageData: <MessageDataType> }One entry per message start event, with that message’s name and data type (any if none is set).

startBy is optional only when the Process has a plain start event.

interface <ProcessName>.ProcessInputData

One property per process variable whose context is input, with the variable’s type. A property is optional when its variable has a default expression.

Availability: Both

interface <ProcessName>.ProcessData

One property per process variable, with the variable’s type, plus publicMetadata: Record<string, any>.

Availability: Server

interface <ProcessName>.TokenData

One property per token variable, with the variable’s type, plus publicMetadata: Record<string, any>.

Availability: Server

interface Sys.Types.ProcessScope<P = Record<string, any>>

The root data of a Process instance, as returned by getRootData().

FieldTypeRequiredDescription
processPyesThe process variables.
initiatorUser | nullyesThe End user who started the Process instance.
startSignalNamestringnoSignal name, when started by a signal start event.
startMessageNamestringnoMessage name, when started by a message start event.
startTimerActivityIdstringnoId of the timer start event, when started by a timer.
startMessageDataanynoMessage data, when started by a message start event.
actionstringnoThe action with which the last user task was completed.

Availability: Everywhere

class Sys.Types.UserTaskToken

An open user task, as returned by startAndGetFirstUserTaskToken().

FieldTypeDescription
idstringId of the task token.
taskNamestringName of the user task.
taskTypeProcessTaskTokenTypeKind of task.
processInstanceIdnumberId of the Process instance.
statusProcessTaskTokenStatus'active' or 'error'.
publicMetadataRecord<string, any>Public metadata of the task (optional).
errorMessage, errorStackstringError details when status is 'error' (optional).
assignedToUserId, assignedToNamestringThe End user the task is assigned to.
processModuleId, processBoIdstringThe Process the task belongs to.
screenModuleId, screenBoIdstringThe screen that shows the task.
swimlaneId, swimlaneNamestringThe lane of the task.

getUrl(): string returns the task’s relative URL, /<screenModuleId>/t/<id>.

Availability: Everywhere

¹ On the client, the call is sent to the server and is subject to access control.