Tasks
Built-in Tasks is a concept feature. It's still being developed and can change before it's released. It's available only when the site's license includes the Concept feature Tasks.
Audience:
Low-code EngineersSkill Prerequisites:
Actions,Tokens,Workflows
The Tasks actions create, assign, complete and read built-in tasks from form buttons, workflows and any other place you add actions. They follow the same rules as the buttons of My Tasks: the same people may do the same things, and every change raises the same events. So the task type's event workflows run whichever way a task was changed.
Choosing an action
| Action | What it does | Use it to |
|---|---|---|
| Create Task | Creates a task of a type for a user or for the members of candidate roles, optionally attached to a record. | Ask the Buyers to check the supplier of a purchase request. |
| Assign Task | Sets the assignee. For Task administrators and escalation workflows. | Give an unassigned purchase check to one buyer. |
| Assign Task to Current User | The current user takes an unassigned task of one of their candidate roles. People see it as Assign to me. | Add an Assign to me button to your own list of tasks. |
| Unassign Task | The assignee gives the task back to its candidate roles. People see it as Unassign. | Let a buyer put an order task back in the pool. |
| Delegate Task | The assignee hands the task to another user. The task remembers who delegated it. | Hand a purchase check to a colleague before a holiday. |
| Reassign Task | A Task administrator sets a new assignee, new candidate roles, or both. | Hand a late order task to the Procurement Leads in an escalation step. |
| Start Task | Moves the task from Open to In progress. | Show that a buyer is working on an order. |
| Complete Task | Completes the task with an outcome of its type. | Complete a purchase check with Looks fine from a form button. |
| Cancel Task | Cancels an open task. For the creator and Task administrators. | Cancel the open tasks of a request that was withdrawn. |
| Update Task | Changes the title, description, priority or due date. | Raise the priority of a late order task to High. |
| Escalate Task | Runs the task's next escalation step now, with a reason. | Let the assignee ask for help before the due date. |
| Read Task | Reads one task into tokens, with what the current user may do with it. | Show a task on a page, and only the buttons the user may use. |
| Get Tasks | Lists the tasks the current user can see, filtered, as JSON. | Count the open tasks of a request, or cancel them all. |
To list tasks in a grid, use the Tasks Data Source instead of Get Tasks.
Who may do what
Each action acts as a person and checks what that person may do with the task. These are the people a task knows:
- Assignee. The one user the task is assigned to. A task may have no assignee. It's then unassigned, and any member of its candidate roles can assign it to themselves.
- Candidate roles. The roles whose members may take the task while it's unassigned.
- Creator. The user who created the task. Tasks created by a lifecycle checklist, or in an escalation step's workflow, have no creator.
- Task administrators of the task's type. These are the roles in the type's Task administrators. When it's empty, the Default task administrators of the Tasks Settings are used, and when that's empty too, the Administrators role. See Task Types.
- Superusers. They see every task and may do everything a Task administrator may. They aren't the assignee or a candidate unless they are one.
- The user who delegated the task. They keep seeing it, read-only.
| Action | Who may run it |
|---|---|
| Create Task | Anyone who can run the action. No task right is checked. |
| Assign Task | Task administrators of the type. |
| Assign Task to Current User | A member of the task's candidate roles, while the task is unassigned. |
| Unassign Task | The assignee, when they're a member of the task's candidate roles. |
| Delegate Task | The assignee. |
| Reassign Task | Task administrators of the type. |
| Start Task | The assignee, while the task is Open. |
| Complete Task | The assignee. With Assign to Me If Unassigned, also a member of the candidate roles of an unassigned task. |
| Cancel Task | The creator and the Task administrators of the type. |
| Update Task | Task administrators of the type. The assignee may change the due date when the type has The assignee can change the due date on. |
| Escalate Task | Task administrators of the type, and the assignee when the type has The assignee can escalate on. |
| Read Task | Anyone who can see the task. |
| Get Tasks | Anyone. The list holds only the tasks they can see. |
A user sees a task when they're its assignee, its creator, the user who delegated it, a member of its candidate roles while it's unassigned, or a Task administrator of its type. A task the user can't see is treated as if it didn't exist.
Only open tasks, Open or In progress, can be changed. A completed or cancelled task stays as it is.
Who the actions act as
- On a page, for example a form button or a grid row button, the actions act as the signed-in user. Anonymous visitors can create tasks, but can't change any.
- In a workflow, they act as the user the workflow runs as, usually the user whose action started it.
- In a task type's event workflow, they act as the user whose change raised the event.
- In an escalation step's workflow, they act as the system. The system may do everything a Task administrator or an assignee may, except assign a task to itself.
- In a BPMN 2.0 workflow, they act as the user the run runs as. After a wait, the run continues as the user who started it.
Users and roles in parameters
There's no user picker. Give a user as a user id, a username or an email address, typed or from a token such as [User:UserID]. A value that matches no user fails with No user matches "<value>".
Candidate roles are picked from the site's roles. Switch Candidate Roles to an expression to give role names or ids from tokens, separated by commas, for example Buyers, Procurement Leads. A name that matches no role fails with No role matches "<value>".
Task fields in tokens
Every action except Get Tasks can publish the task it worked on. Set Output Token Name, for example to Task. Then [Task] holds the task id and these tokens hold its fields. Get Tasks gives the same fields for each task in its JSON.
| Token | Value |
|---|---|
[Task:Id] | The task id. |
[Task:Title] | The title. |
[Task:Description] | The description. |
[Task:Type] | The key of the task type, for example purchase-check. |
[Task:Status] | open, inProgress, completed or cancelled. |
[Task:StatusName] | Open, In progress, Completed or Cancelled. |
[Task:Outcome] | The key of the outcome the task was completed with. Empty until then. |
[Task:Assignee] | The user id of the assignee. Empty while the task is unassigned. |
[Task:OwnedBy] | The same as [Task:Assignee]. |
[Task:CandidateRoles] | The role ids of the candidate roles, separated by commas. |
[Task:DelegatedBy] | The user id of the user who delegated the task. Empty if it wasn't delegated. |
[Task:DueDate] | The due date, in ISO 8601 format, for example 2026-11-20T17:00:00.0000000+00:00. Empty when there's none. |
[Task:Overdue] | true while the task is open and the due-date job has marked it overdue, otherwise false. |
[Task:OverdueOn] | When the due-date job marked the task overdue. Empty when it hasn't. |
[Task:Priority] | Low, Normal, High or Urgent. |
[Task:CreatedBy] | The user id of the creator. -1 when the task has no creator. |
[Task:CreatedDate] | When the task was created. |
[Task:CompletedBy] | The user id of the user who completed the task. Empty while it's open, and when an escalation workflow completed it. |
[Task:CompletedOn] | When the task was completed. |
[Task:CompletionComment] | The comment given when the task was completed or cancelled. |
[Task:EscalationStep] | The number of the last escalation step that ran, starting at 1. Empty when none has run. |
[Task:EscalatedOn] | When the last escalation step ran. |
All dates are in ISO 8601 format. Read Task adds names and what the current user may do, such as [Task:AssigneeName] and [Task:CanComplete].
Event and escalation workflows get the task as [Task:...] tokens too, with a few more for notifications. See Due Dates, Escalation and Events.
Errors and refusals
When the rules refuse a change or a value is wrong, the action fails with a short message written for the person using the app, for example Only the assignee can complete this task. Each action page lists its messages.
- On Error runs first. The action's On Error actions get the message in
[ExceptionMessage], with[Exception],[ExceptionType]and[ExceptionStack]. - Then the action still fails, unless an On Error action ends execution itself, for example Display Error Message or Stop Execution. Administrators and low-code engineers see the message. Other users see a generic error.
- To show the reason to everyone, put Display Error Message with
[ExceptionMessage]in On Error.
These messages can come from any of the actions:
| Message | Why |
|---|---|
Task #<id> was not found or you cannot see it. | There's no such task, or the user can't see it. |
"<value>" is not a task id. | Task Id is empty or isn't a number, for example because its token is empty. |
This task is <status>, so you cannot <change> it. | The task is completed or cancelled. |
Someone else changed this task first. Reload it and try again. | Two changes to the same task were made at the same moment. Only the first is saved. |
Tasks feature is unlicensed | The site's license doesn't include the Concept feature Tasks. |
Events
Every change raises one event after it's saved. The workflow the task type binds to that event in its Event workflows then runs, before the action finishes. If that workflow fails, the error is logged, and the change and the action still succeed. An event workflow can run Tasks actions itself, which raise their own events, up to 10 levels deep. See Due Dates, Escalation and Events.
| Action | Event | Reason |
|---|---|---|
| Create Task | Created | |
| Assign Task | Assigned | assign, or reassign when the task already had an assignee |
| Assign Task to Current User | Assigned | claim |
| Unassign Task | Unassigned | |
| Delegate Task | Assigned | delegate |
| Reassign Task | Assigned | reassign |
| Start Task | Started | |
| Complete Task | Completed, with the outcome. With Assign to Me If Unassigned on an unassigned task, Assigned with claim comes first. | |
| Cancel Task | Cancelled | |
| Update Task | Due date changed, only when the due date changes | |
| Escalate Task | Escalated | manual |
The Comment of an action reaches the event workflow as [Comment].
There's no Automation trigger on task events yet. To react to a change, bind a workflow to the event in the task type.
Tasks in BPMN 2.0 workflows
In a BPMN 2.0 workflow, the Tasks actions run in a service task like any other action, and none of them waits. Create Task creates the task and the run moves on.
To make a run wait until a person completes a task, use a user task. It holds one Create Task action with an Output Token Name, and the run continues when the task is completed or cancelled. See User Tasks.
Revised 11/12/2026