Skip to content

Sys.Process

Sys.Process works with Processes at runtime. Server-side code can start Process instances, send them signals and messages, read and change their data, find and assign user tasks, and cancel or delete instances. Client-side code works with the user tasks of the logged-in End user: it finds and opens them, assigns them, and completes the current task to move the Process forward.

To start a specific Process, you usually call start() on the Process Business Object instead (This.<ProcessName>.start(...)), which calls Sys.Process.startProcess() for you.

A Process is identified by its qualified name, <moduleId>.<ProcessName>. Functions that take an optional assertProcessQualifiedName throw if the Process instance is not of that Process.

Availability: Both

startProcess(qualifiedName: string, inputData: Record<string, any>, startyBy: StartByType, branchName?: BranchNameType, initiator?: User): Promise<number>

Starts a new Process instance and returns its ID once the Process has started running.

ParameterTypeDescription
qualifiedNamestringQualified name of the Process, for example Purchasing.PurchaseRequestProcess.
inputDataRecord<string, any>Input data, from which the Process creates its initial data.
startyByStartByTypeWhich start event to start at: 'normal' for the plain start event, or an object naming a message, signal or timer start event (see below).
branchNameBranchNameTypeOptional. Branch whose Process definition to use. Default: the current branch.
initiatorUserOptional. The user who starts the Process; available to the Process as initiator. Default: the current user.

StartByType object fields

FieldTypeRequiredDescription
messageNamestringOptionalStarts at the message start event for this message.
messageDataanyOptionalData passed with the message.
signalNamestringOptionalStarts at the signal start event for this signal.
startActivityIdstringOptionalStarts at the timer start event with this ID.

Note

If the Process does not exist on the branch, Lowgile logs an error and the promise resolves to undefined instead of rejecting.

Returns: Promise<number> · Availability: Server

startProcessAndGetFirstUserTaskToken(qualifiedName: string, inputData: Record<string, any>, startyBy: StartByType, branchName?: BranchNameType, initiator?: User, taskTimeoutMs?: number, taskDebounceMs?: number): Promise<{
instanceId: number;
taskToken: UserTaskToken;
}>

Starts a new Process instance like startProcess() and waits for its first user task that the current user may work on, so the caller can open that task right away.

Lowgile waits up to taskTimeoutMs for a user task of the new instance. Once one appears, it waits taskDebounceMs for further ones and picks the one with the highest priority. A user task marked as preferred is taken at once.

ParameterTypeDescription
qualifiedNamestringQualified name of the Process.
inputDataRecord<string, any>Input data for the Process.
startyByStartByTypeWhich start event to start at; see startProcess().
branchNameBranchNameTypeOptional. Default: the current branch.
initiatorUserOptional. Default: the current user.
taskTimeoutMsnumberOptional. How long to wait for a user task, in milliseconds. -1 doesn’t wait. Default: 1500.
taskDebounceMsnumberOptional. How long to wait for further user tasks after the first, in milliseconds. -1 doesn’t wait. Default: 100.

Returns: Promise<{ instanceId: number; taskToken: UserTaskToken }>, where taskToken is undefined if no user task became available in time · Availability: Server

// server-side
driveProcess(message: z.infer<typeof driveProcessSchema>): Promise<UserTaskToken>
// client-side
driveProcess(action: string, data: any, tokenId?: string): Promise<any>

Completes a user task with one of its actions and moves the Process instance forward. Lowgile runs the task’s output handler for the action, which copies data into the Process data. If the handler returns false, the changes are saved but the Process does not move on. If it returns a string, that string is used as the action.

The task must be assigned to the current user.

Server-side parameter:

ParameterTypeDescription
messageobjectWhat to do, with the fields below.

message fields

FieldTypeRequiredDescription
tokenIdstringRequiredID of the user task.
actionstringRequiredThe action (output) to complete the task with.
dataanyRequiredData for the output handler, usually the task Screen’s output values.
getFirstUserTaskToken{ taskTimeoutMs?: number; taskDebounceMs?: number }OptionalIf set, waits for the next user task the current user may work on and returns it, as described for startProcessAndGetFirstUserTaskToken(). Defaults: 1500 and 150 milliseconds.

Client-side parameters:

ParameterTypeDescription
actionstringThe action (output) to complete the task with.
dataanyData for the output handler.
tokenIdstringOptional. ID of the user task. Default: the task the End user is currently on.

Note

On the server side, the promise resolves to undefined if getFirstUserTaskToken is not set, if no user task became available in time, or if the output handler stopped the Process. On the client side, it never waits for a next task and resolves to undefined.

Returns: Promise<UserTaskToken> on the server side, Promise<any> on the client side · Availability: Both

driveProcessAndGetFirstUserTaskToken(action: string, data: any, tokenId?: string, taskTimeoutMs?: number, taskDebounceMs?: number): Promise<any>

Completes a user task like driveProcess() and waits for the next user task the End user may work on.

ParameterTypeDescription
actionstringThe action (output) to complete the task with.
dataanyData for the output handler.
tokenIdstringOptional. ID of the user task. Default: the task the End user is currently on; throws if there is none.
taskTimeoutMsnumberOptional. How long to wait for a next task, in milliseconds. -1 doesn’t wait. Default: 1500.
taskDebounceMsnumberOptional. How long to wait for further tasks after the first, in milliseconds. -1 doesn’t wait. Default: 150.

Returns: Promise<any>, the next UserTaskToken or undefined · Availability: Client

driveProcessAndFollowNextUserTask(action: string, data: any, tokenId?: string, taskTimeoutMs?: number, taskDebounceMs?: number, extras?: NavigationExtras): Promise<void>

Completes a user task like driveProcessAndGetFirstUserTaskToken() and then opens the next task in place of the current one. If there is no next task, the app goes back to its home page. This is what the actions on a task Screen usually do.

ParameterTypeDescription
actionstringThe action (output) to complete the task with.
dataanyData for the output handler.
tokenIdstringOptional. ID of the user task. Default: the task the End user is currently on.
taskTimeoutMsnumberOptional. How long to wait for a next task, in milliseconds. Default: 1500.
taskDebounceMsnumberOptional. How long to wait for further tasks, in milliseconds. Default: 150.
extrasNavigationExtrasOptional. Angular router options for opening the next task.

Note

If the Developer bar setting to go home on a swimlane change is on, the next task is only opened if it is in the same swimlane as the current one.

Returns: Promise<void> · Availability: Client

sendSignal(processInstanceId: number, signalName: string, assertProcessQualifiedName?: string): Promise<void>

Sends a signal to a running Process instance, triggering its signal events with that name.

ParameterTypeDescription
processInstanceIdnumberID of the Process instance.
signalNamestringName of the signal as defined in the Process. Throws if the Process has no such signal.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Returns: Promise<void> · Availability: Server

sendMessage(processInstanceId: number, messageName: string, messageData: any, assertProcessQualifiedName?: string): Promise<void>

Sends a message with data to a running Process instance, triggering its message events with that name.

ParameterTypeDescription
processInstanceIdnumberID of the Process instance.
messageNamestringName of the message as defined in the Process. Throws if the Process has no such message.
messageDataanyData passed with the message.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Returns: Promise<void> · Availability: Server

// server-side
getTaskById(tokenId: string, asUser?: User): Promise<UserTaskToken>
// client-side
getTaskById(tokenId: string): Promise<UserTaskToken | undefined>

Gets a user task by ID. On the client side, only tasks the End user may see are found.

ParameterTypeDescription
tokenIdstringID of the user task.
asUserUserServer-side only. Optional. Only finds the task if this user may see it: it is assigned to them, or they are allowed to take it. Default: no restriction.

Returns: Promise<UserTaskToken>, undefined if not found · Availability: Both

// server-side
getTaskDetailsById(tokenId: string, includeAssignments: boolean, asUser?: User): Promise<UserTaskTokenDetails>
// client-side
getTaskDetailsById(tokenId: string, includeAssignments: boolean): Promise<UserTaskTokenDetails | undefined>

Gets a user task with the details needed to show it: its outputs and outgoing flows, the swimlane and, optionally, the values for the task Screen’s inputs.

ParameterTypeDescription
tokenIdstringID of the user task.
includeAssignmentsbooleanWhether to calculate the task Screen’s input values from the current Process data (assignments).
asUserUserServer-side only. Optional. Only finds the task if this user may see it. Default: no restriction.

Returns: Promise<UserTaskTokenDetails>, undefined if not found · Availability: Both

getTaskDetailsByIds(tokenIds: string[], includeAssignments: boolean, asUser?: User): Promise<UserTaskTokenDetails[]>

Gets several user tasks with details, like getTaskDetailsById(). Tasks that are not found are left out.

ParameterTypeDescription
tokenIdsstring[]IDs of the user tasks.
includeAssignmentsbooleanWhether to calculate the task Screens’ input values.
asUserUserOptional. Only finds tasks this user may see. Default: no restriction.

Returns: Promise<UserTaskTokenDetails[]> · Availability: Server

// server-side
getAllTasksForUser(filter: UserRelatedTokenFilter, asUser?: User): Promise<UserTaskToken[]>
// client-side
getAllTasksForUser(filter: UserRelatedTokenFilter): Promise<UserTaskToken[]>

Gets the user tasks of a user: those assigned to them and those they are allowed to take, as chosen in filter. Use it for a task list.

ParameterTypeDescription
filterUserRelatedTokenFilterWhose tasks, and which kinds of tasks, to get.
asUserUserServer-side only. Optional. The user making the request. Default: the current user.

UserRelatedTokenFilter fields

FieldTypeRequiredDescription
userIdstringOptionalUser whose tasks to get. Default: the requesting user. Getting another user’s tasks requires the system Permission SeeAllProcessTasks.
includeAssignedbooleanOptionalInclude tasks assigned to the user.
includeUserAllowedbooleanOptionalInclude unassigned tasks the user is allowed to take by name.
includeRoleAllowedbooleanOptionalInclude unassigned tasks the user is allowed to take through one of their Roles.
includeGroupAllowedbooleanOptionalInclude unassigned tasks the user is allowed to take through one of their groups.
moduleIdsstring[] | '*'OptionalOnly tasks of Processes in these modules. Default: '*', all modules.

With none of the include… fields set, the result is empty.

const myTasks = await Sys.Process.getAllTasksForUser({
includeAssigned: true,
includeUserAllowed: true,
includeRoleAllowed: true,
includeGroupAllowed: true,
})

Returns: Promise<UserTaskToken[]> · Availability: Both

// server-side
getPagedTasksForUser(filter: UserRelatedTokenFilter, paging: PagingDefinition, sorting?: SortingDefinition<keyof UserTaskToken>, asUser?: User): Promise<PagedData<UserTaskToken>>
// client-side
getPagedTasksForUser(filter: UserRelatedTokenFilter, paging: PagingDefinition, sorting?: SortingDefinition<keyof UserTaskToken>): Promise<PagedData<UserTaskToken>>

Gets one page of a user’s tasks, like getAllTasksForUser().

ParameterTypeDescription
filterUserRelatedTokenFilterWhose tasks, and which kinds of tasks, to get; see getAllTasksForUser().
pagingPagingDefinitionWhich page: pageSize and pageIndex (from 0).
sortingSortingDefinition<keyof UserTaskToken>Optional. Sort order: by (a field name) and direction ('asc' or 'desc', default 'asc').
asUserUserServer-side only. Optional. The user making the request. Default: the current user.

Returns: Promise<PagedData<UserTaskToken>> · Availability: Both

getAllTasks(filter?: AllTokenFilter, sorting?: SortingDefinition<keyof ProcessTaskToken>): Promise<ProcessTaskToken[]>

Gets all open tasks of all users, without any access check.

ParameterTypeDescription
filterAllTokenFilterOptional. Has one field, moduleIds (string[] | '*'): only tasks of Processes in these modules. Default: all modules.
sortingSortingDefinition<keyof ProcessTaskToken>Optional. Sort order: by and direction.

Note

The returned objects are UserTaskToken objects, not ProcessTaskToken objects as declared.

Returns: Promise<ProcessTaskToken[]> · Availability: Server

getAllTasksPaged(filter?: AllTokenFilter, paging?: PagingDefinition, sorting?: SortingDefinition<keyof ProcessTaskToken>): Promise<PagedData<ProcessTaskToken>>

Gets one page of all open tasks of all users, like getAllTasks().

ParameterTypeDescription
filterAllTokenFilterOptional. Only tasks of Processes in the modules in moduleIds. Default: all modules.
pagingPagingDefinitionOptional. Which page: pageSize and pageIndex. Default: all tasks.
sortingSortingDefinition<keyof ProcessTaskToken>Optional. Sort order: by and direction.

Note

The list contains UserTaskToken objects, not ProcessTaskToken objects as declared.

Returns: Promise<PagedData<ProcessTaskToken>> · Availability: Server

// server-side
assignTaskToUser(tokenId: string, toUserOrIdOrUsername: User | string | null, reassignIfAssigned?: boolean, asUser?: User): Promise<void>
// client-side
assignTaskToUser(tokenId: string, toUserIdOrUsername: string | undefined, reassignIfAssigned?: boolean): Promise<void>

Assigns a user task to a user, or removes its assignment. A user may assign an unassigned task to themselves if they are allowed to take it. Assigning tasks to others requires the system Permission AssignProcessTasks; taking a task away from another user also requires UnassignProcessTasks. On the client side, the requesting user is the logged-in End user, and the current task reloads if it is the one changed.

ParameterTypeDescription
tokenIdstringID of the user task.
toUserOrIdOrUsernameUser | string | nullThe user to assign the task to, as user, ID or user name; null removes the assignment. On the client side, an ID or user name.
reassignIfAssignedbooleanOptional. Whether to take the task away from another user it is assigned to. Default: false, which throws if it is assigned to someone else.
asUserUserServer-side only. Optional. The user making the request, whose Permissions are checked. Default: no check.

Returns: Promise<void> · Availability: Both

assignTokenToCurrentUser(tokenId: string): Promise<void>

Assigns an unassigned user task to the current user. Throws if no user is logged in or if the task is assigned to someone else.

ParameterTypeDescription
tokenIdstringID of the user task.

Returns: Promise<void> · Availability: Server

assignTaskToCurrentUser(tokenId: string): Promise<void>

Assigns an unassigned user task to the logged-in End user, if they are allowed to take it.

ParameterTypeDescription
tokenIdstringID of the user task.

Returns: Promise<void> · Availability: Client

assignCurrentTaskToCurrentUser(): Promise<void>

Assigns the task the End user is currently on to them, for example from a “Take task” button. Throws if the End user is not on a task.

Returns: Promise<void> · Availability: Client

unassignTaskToUser(tokenId: string, asUser?: User): Promise<void>

Removes the assignment of a user task, so that it can be taken again.

ParameterTypeDescription
tokenIdstringID of the user task.
asUserUserOptional. The user making the request. Users may unassign their own tasks; others’ tasks require the system Permissions AssignProcessTasks and UnassignProcessTasks. Default: no check.

Returns: Promise<void> · Availability: Server

unassignTask(tokenId: string): Promise<void>

Removes the assignment of a user task as the logged-in End user. End users may unassign their own tasks; others’ tasks require the system Permissions AssignProcessTasks and UnassignProcessTasks. The current task reloads if it is the one changed.

ParameterTypeDescription
tokenIdstringID of the user task.

Returns: Promise<void> · Availability: Client

getPossibleTaskAssignees(tokenId: string): Promise<UserRecord[]>

Lists the users allowed to take a user task, by name, Role or group, sorted by name. Each UserRecord includes e-mail address and phone number.

ParameterTypeDescription
tokenIdstringID of the user task. Throws if there is no such task.

Returns: Promise<UserRecord[]> · Availability: Server

navigateToTask(tokenOrId: UserTaskToken | string, inNewWindow: boolean | string, extras?: NavigationExtras): Promise<void>

Opens a user task’s Screen. A task of the current app opens within the app; a task of another app, or one opened in a new window, opens by URL.

ParameterTypeDescription
tokenOrIdUserTaskToken | stringThe task, or its ID. Throws if no task with this ID is found.
inNewWindowboolean | stringtrue opens a new browser window or tab; a string opens it in the window with that name; false opens it in the current window.
extrasNavigationExtrasOptional. Angular router options, used when the task opens within the app.

Returns: Promise<void> · Availability: Client

cancelProcessFromTask(tokenId: string, redirectToHomeScreen?: boolean): Promise<void>

Cancels the Process instance that a user task belongs to. The End user must be allowed to see the task.

ParameterTypeDescription
tokenIdstringID of a user task of the instance.
redirectToHomeScreenbooleanOptional. Whether to go to the app’s home page afterwards. Default: false.

Returns: Promise<void> · Availability: Client

cancelCurrentProcess(): Promise<void>

Cancels the Process instance of the task the End user is currently on, and goes to the app’s home page. Throws if the End user is not on a task.

Returns: Promise<void> · Availability: Client

getProcessInstances(options?: FindManyOptions<ProcessInstance>): Promise<ProcessInstance[]>

Reads Process instances from the database.

ParameterTypeDescription
optionsFindManyOptions<ProcessInstance>Optional. TypeORM find options, such as where, order, skip and take. Default: all instances.
const running = await Sys.Process.getProcessInstances({
where: { moduleId: 'Purchasing', boId: 'PurchaseRequestProcess', status: 'running' },
})

Returns: Promise<ProcessInstance[]> · Availability: Server

cancelProcessInstance(instanceId: number, assertProcessQualifiedName?: string): Promise<void>

Cancels a running or suspended Process instance: its open tasks and data are removed, and its status becomes terminated. The instance itself and its history are kept. Throws if the instance is already completed or terminated.

ParameterTypeDescription
instanceIdnumberID of the Process instance.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Returns: Promise<void> · Availability: Server

cancelAllRunningProcessInstances(): Promise<void>

Cancels all running Process instances of all Processes: their status becomes terminated and their open tasks are removed.

Returns: Promise<void> · Availability: Server

terminateProcessInstance(instanceId: number, assertProcessQualifiedName?: string): Promise<void>

Stops a Process instance and removes its open tasks, swimlane assignments and data.

ParameterTypeDescription
instanceIdnumberID of the Process instance.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Note

Unlike cancelProcessInstance(), this does not change the instance’s status, so it keeps its status, such as running. The assertProcessQualifiedName check is only made if the instance is currently loaded in memory. Prefer cancelProcessInstance().

Returns: Promise<void> · Availability: Server

deleteProcessInstance(instanceId: number, assertProcessQualifiedName?: string): Promise<void>

Stops a Process instance and deletes it with all its tasks, data and history.

ParameterTypeDescription
instanceIdnumberID of the Process instance.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Returns: Promise<void> · Availability: Server

deleteAllProcessInstances(): Promise<void>

Deletes all Process instances of all Processes, with their history. Use it to reset test data.

Returns: Promise<void> · Availability: Server

getProcessInstanceId(): number

Returns the ID of the Process instance whose code is running, for example in a script task, a task output handler or an on-arrival handler.

Note

Outside Process code, it returns undefined.

Returns: number · Availability: Server

getProcessTaskTokenId(): string

Returns the ID of the user task whose on-arrival handler is running.

Note

Outside a user task’s on-arrival handler, it returns undefined.

Returns: string · Availability: Server

getRootDataOfProcessInstance(instanceId: number, assertProcessQualifiedName?: string): Promise<any>

Reads the data of a Process instance: the Process variables in process, the initiator, and the last action, as a ProcessScope.

ParameterTypeDescription
instanceIdnumberID of the Process instance.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.

Returns: Promise<any> · Availability: Server

updateRootDataOfProcessInstance(instanceId: number, updateData: Partial<ProcessScope>, assertProcessQualifiedName?: string): Promise<void>
updateRootDataOfProcessInstance<T>(instanceId: number, updateFn: (data: ProcessScope) => T | Promise<T>, assertProcessQualifiedName?: string): Promise<T>
updateRootDataOfProcessInstance<T>(instanceId: number, dataOrFn: Partial<ProcessScope> | ((data: ProcessScope) => any | Promise<T>), assertProcessQualifiedName?: string): Promise<T>

Changes the data of a Process instance while holding its lock, then saves it. Pass either an object whose top-level fields replace those of the data, or a function that changes the data in place.

ParameterTypeDescription
instanceIdnumberID of the Process instance.
updateData / updateFnPartial<ProcessScope> or (data: ProcessScope) => T | Promise<T>The fields to replace, or a function that changes data. The function’s return value is returned.
assertProcessQualifiedNamestringOptional. Qualified name the Process must have.
await Sys.Process.updateRootDataOfProcessInstance(instanceId, (data) => {
data.process.request.priority = 'high'
})

Returns: Promise<void> for an object; Promise<T>, the function’s result, for a function · Availability: Server

get currentTaskTokenId(): string;

ID of the user task the End user is currently on, or null if the current Screen is not a task.

Type: string · Availability: Client

get currentTaskDetails(): any;

The UserTaskTokenDetails of the current task, including the Screen input values (assignments), or undefined while they load or if the current Screen is not a task.

Type: any · Availability: Client

get isProcessTask(): boolean;

Whether the current Screen is shown as a user task.

Type: boolean · Availability: Client

get isUnassignedTask(): boolean;

Whether the current task is not assigned to anyone yet. Use it, for example, to show a “Take task” button.

Type: boolean · Availability: Client

get isAssignedTask(): boolean;

Whether the current task is assigned to someone.

Type: boolean · Availability: Client

A Process instance as stored in the database, as returned by getProcessInstances(). Its main fields are id, branchName, moduleId and boId (the module and name of the Process), and status: 'running', 'suspended', 'completed' or 'terminated'. Its other members are used by the Process engine.

Availability: Server

A user task as returned by the task functions. It is part of Sys.Types. Its fields are id, taskName, taskType, status, processInstanceId, processModuleId and processBoId (the Process), screenModuleId and screenBoId (the task Screen), assignedToUserId and assignedToName, swimlaneId and swimlaneName, and publicMetadata. Its method getUrl() returns the task’s URL path.

UserTaskTokenDetails adds assignments (the task Screen’s input values as name–value pairs), outputs (the task’s actions), outgoingFlows, layoutScreenModuleId and layoutScreenBoId.

Availability: Both