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¹
How to reach it
Section titled “How to reach it”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).
Functions
Section titled “Functions”start()
Section titled “start()”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.
| Parameter | Type | Description |
|---|---|---|
inputData | <ProcessName>.ProcessInputData | Values 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 Processconst 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()
Section titled “startAndGetFirstUserTaskToken()”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.
| Parameter | Type | Description |
|---|---|---|
inputData | <ProcessName>.ProcessInputData | Values for the Process’s input variables. |
startBy | <StartByUnion> | Which start event to use. Optional when the Process has a plain start event, required otherwise. |
taskTimeoutMs | number | How long to wait for a user task, in milliseconds. Default 1500. |
taskDebounceMs | number | How 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()
Section titled “startAndNavigateToFirstUserTask()”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.
| Parameter | Type | Description |
|---|---|---|
inputData | <ProcessName>.ProcessInputData | Values for the Process’s input variables. |
isNewWindow | boolean | string | false 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. |
failIfNoUserTask | boolean | Throw an error when no user task appears within the timeout. Default true. |
taskTimeoutMs | number | How long to wait for a user task, in milliseconds. Default 1500. |
taskDebounceMs | number | How 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()
Section titled “terminateProcessInstance()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
Returns: Promise<void> · Availability: Server
cancelProcessInstance()
Section titled “cancelProcessInstance()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
Returns: Promise<void> · Availability: Server
deleteProcessInstance()
Section titled “deleteProcessInstance()”deleteProcessInstance(processInstanceId: number): Promise<void>Terminates a Process instance, then deletes it together with its recorded Step executions.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
Returns: Promise<void> · Availability: Server
sendSignal()
Section titled “sendSignal()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
signalName | <SignalName> | Name of the signal. |
Returns: Promise<void> · Availability: Server
sendMessage()
Section titled “sendMessage()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id 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()
Section titled “getRootData()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
Returns: Promise<Sys.Types.ProcessScope<<ProcessName>.ProcessData>> · Availability: Server
updateRootData()
Section titled “updateRootData()”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.
| Parameter | Type | Description |
|---|---|---|
processInstanceId | number | Id of the Process instance. |
updateData | Partial<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 othersawait This.$Process.PurchaseRequest.updateRootData(instanceId, (data) => { data.process.isUrgent = true})startBy
Section titled “startBy”The values accepted by the startBy parameter are generated from the Process’s start events, as a union of:
| Value | When 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.
ProcessInputData
Section titled “ProcessInputData”interface <ProcessName>.ProcessInputDataOne 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
ProcessData
Section titled “ProcessData”interface <ProcessName>.ProcessDataOne property per process variable, with the variable’s type, plus publicMetadata: Record<string, any>.
Availability: Server
TokenData
Section titled “TokenData”interface <ProcessName>.TokenDataOne property per token variable, with the variable’s type, plus publicMetadata: Record<string, any>.
Availability: Server
ProcessScope
Section titled “ProcessScope”interface Sys.Types.ProcessScope<P = Record<string, any>>The root data of a Process instance, as returned by getRootData().
| Field | Type | Required | Description |
|---|---|---|---|
process | P | yes | The process variables. |
initiator | User | null | yes | The End user who started the Process instance. |
startSignalName | string | no | Signal name, when started by a signal start event. |
startMessageName | string | no | Message name, when started by a message start event. |
startTimerActivityId | string | no | Id of the timer start event, when started by a timer. |
startMessageData | any | no | Message data, when started by a message start event. |
action | string | no | The action with which the last user task was completed. |
Availability: Everywhere
UserTaskToken
Section titled “UserTaskToken”class Sys.Types.UserTaskTokenAn open user task, as returned by startAndGetFirstUserTaskToken().
| Field | Type | Description |
|---|---|---|
id | string | Id of the task token. |
taskName | string | Name of the user task. |
taskType | ProcessTaskTokenType | Kind of task. |
processInstanceId | number | Id of the Process instance. |
status | ProcessTaskTokenStatus | 'active' or 'error'. |
publicMetadata | Record<string, any> | Public metadata of the task (optional). |
errorMessage, errorStack | string | Error details when status is 'error' (optional). |
assignedToUserId, assignedToName | string | The End user the task is assigned to. |
processModuleId, processBoId | string | The Process the task belongs to. |
screenModuleId, screenBoId | string | The screen that shows the task. |
swimlaneId, swimlaneName | string | The lane of the task. |
getUrl(): string returns the task’s relative URL, /<screenModuleId>/t/<id>.
Availability: Everywhere
Related
Section titled “Related”- Processes
- Sys.Process
- Sys.Types
- Access Control
¹ On the client, the call is sent to the server and is subject to access control.