Get Tasks

Concept

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 Engineers

Skill Prerequisites: Actions, Lists, Tokens

Lists the tasks the current user can see, with filters, into a token as JSON, with their number and their ids.

Typical Use Cases

• Count the open tasks of a purchase request, for example before letting someone close it
• Cancel or complete every open task of a record, together with Execute Actions for each List Entry
• List the tasks that the same lifecycle checklist created as a given task
• List the user's overdue tasks of one type

Don't use it to

• Show tasks in a grid. Use the Tasks Data Source instead. It has the same filters.
• Read one task whose id you know. Use Read Task instead.

Related Actions

Action Name	Description
Read Task	Reads one task, with what the current user may do with it.
Create List from JSON	Turns the JSON of this action into a list.
Execute Actions for each List Entry	Runs actions once for each task in the list.
Cancel Task	Cancels an open task.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
View	Which tasks to list. See Views.	Yes, as an expression	Every task I can see	No
Task Types	Only tasks of these types. Give the type keys, not the names, separated by commas, for example purchase-check, purchase-order.	Yes	empty	No
States	Only tasks in these states: open, inProgress, completed or cancelled, separated by commas.	Yes	empty	No
In the Same Checklist as Task	A task id, for example [Task:Id] in a task type's Completed workflow. Only the tasks that the same lifecycle checklist created are listed, that task included. A task that isn't part of a checklist matches no task.	Yes	empty	No
Attached To	Only tasks attached to the record in Record Id through this relation, for example Purchase Request › Tasks.	Yes, as an expression	empty	No
Record Id	The id of the record the tasks are attached to, for example [PurchaseRequestId].	Yes	empty	With Attached To
Assignee	Only tasks assigned to this user: a user id, username or email, or a token such as [User:UserID].	Yes	empty	No
Unassigned Only	When checked, only unassigned tasks.	No	false	No
Candidate Roles	Only tasks with at least one of these candidate roles. Pick roles from the list, or switch to an expression and give role names or ids separated by commas.	Yes, as an expression	empty	No
Created By	Only tasks this user created: a user id, username or email, or a token.	Yes	empty	No
Priority	Only tasks of this priority: Low, Normal, High or Urgent.	Yes, as an expression	empty	No
Overdue Only	When checked, only open tasks that the due-date job has marked overdue.	No	false	No
Max Results	The most tasks to list. At most 1000.	Yes	100	No
Output Token Name	The name of a token, without brackets, that receives the list, for example OpenTasks. See Output.	No	empty	Yes, to get the list
On Error	Actions to run when the tasks can't be listed. [ExceptionMessage] holds the reason. See Errors and refusals.	No	empty	No

Views

View	Value in an expression	Lists
Every task I can see	All	Every task the user can see.
Assigned to me	AssignedToMe	The open tasks assigned to the user.
Unassigned	AvailableToClaim	The open, unassigned tasks of the user's candidate roles.
Created by me	CreatedByMe	The tasks the user created, open or not.
Delegated by me	DelegatedByMe	The tasks the user delegated.
Completed or cancelled	Completed	The completed and cancelled tasks the user can see.
Types I administer	Administered	Every task of the types the user is a Task administrator of. For a superuser, every task.

Output

Token	Description
[<Output Token Name>]	The tasks as a JSON array. Each task is an object with the fields of Task fields in tokens, for example Id, Title, Status, Assignee and DueDate.
[<Output Token Name>:Count]	The number of tasks in the list, at most Max Results. 0 when none matches.
[<Output Token Name>:Ids]	The ids of the tasks, separated by commas.

To run actions for each task, load [<Output Token Name>] with Create List from JSON, then use Execute Actions for each List Entry. See Example 2.

Considerations

• Only what the user can see. The filters narrow the tasks the user can see. They never widen them. See Who may do what. In a task type's event workflow, that's the user whose change raised the event. For example, a buyer who completed a purchase check doesn't see the unassigned checks of the Finance Controllers, so they aren't listed.
• The order. Tasks with a due date come first, the earliest first. Then the tasks without a due date. Tasks with the same due date are listed newest first.
• Count is what's listed. [<Output Token Name>:Count] never exceeds Max Results. An empty or invalid Max Results lists at most 100 tasks.
• Empty filters are ignored. A filter whose token comes out empty doesn't filter, so the list can be wider than you expect. Two filters work the other way: Attached To with an empty Record Id, and In the Same Checklist as Task with a token that comes out empty, match no task.
• Overdue Only lists the tasks the due-date job has marked. A task whose due date just passed counts from the job's next run.
• Keys, not names. Task Types takes type keys and States takes the state keys above.

The action can fail with these messages, besides the ones in Errors and refusals:

Message	Why
No user matches "<value>".	Assignee or Created By is a username or email that matches no user.
No role matches "<value>".	A role in Candidate Roles doesn't exist.
Records can be attached to a task only through a relation from their entity to Task. Add one in the entity designer.	Attached To names a relation that doesn't lead to Task.

Examples

tip

To understand how to use the below examples, please see Running Examples.

In these examples, [PurchaseRequestId] holds the id of a purchase request. After importing, pick Purchase Request › Tasks in Attached To, which replaces the placeholder relation id.

1. Count the open tasks of a purchase request

This action lists the open and in-progress tasks attached to the request that the user can see. [OpenTasks:Count] holds their number.

{
    "Title": "Get Tasks",
    "ActionType": "PlantAnApp.Tasks.GetTasks",
    "Description": "Count the open tasks of the request",
    "Condition": null,
    "Parameters": {
        "States": "open, inProgress",
        "AttachedTo": {
            "Expression": "",
            "Value": "00000000-0000-0000-0000-000000000000",
            "IsExpression": false,
            "Parameters": {}
        },
        "AttachedRecordId": "[PurchaseRequestId]",
        "OutputToken": "OpenTasks",
        "OnError": []
    }
}

2. Cancel the open tasks of a purchase request

Run these actions as a Task administrator of the tasks' types, for example in the workflow that withdraws a request. The first lists the open tasks, the second turns them into the OpenTasksList list, and the third cancels each one. Inside the loop, [OpenTasksList:Id] holds the task's id.

[
    {
        "Title": "Get Tasks",
        "ActionType": "PlantAnApp.Tasks.GetTasks",
        "Description": "List the open tasks of the request",
        "Condition": null,
        "Parameters": {
            "States": "open, inProgress",
            "AttachedTo": {
                "Expression": "",
                "Value": "00000000-0000-0000-0000-000000000000",
                "IsExpression": false,
                "Parameters": {}
            },
            "AttachedRecordId": "[PurchaseRequestId]",
            "MaxResults": "1000",
            "OutputToken": "OpenTasks",
            "OnError": []
        }
    },
    {
        "Title": "Create List from JSON",
        "ActionType": "LoadEntitiesFromJson",
        "Description": "Turn the tasks into a list",
        "Condition": "[OpenTasks:Count] != \"0\"",
        "Parameters": {
            "JsonModel": "[OpenTasks]",
            "EntityName": "OpenTasksList",
            "EnforceISODateTime": true,
            "OnError": []
        }
    },
    {
        "Title": "Execute Actions for each List Entry",
        "ActionType": "ExecuteActionsOnEntityList",
        "Description": "Cancel each open task",
        "Condition": "[OpenTasks:Count] != \"0\"",
        "Parameters": {
            "EntityName": "OpenTasksList",
            "Filters": [],
            "ContextBehavior": {
                "Expression": "",
                "Value": "NoPreserve",
                "IsExpression": false,
                "Parameters": {}
            },
            "ActionList": [
                {
                    "Title": "Cancel Task",
                    "ActionType": "PlantAnApp.Tasks.CancelTask",
                    "Description": "Cancel the task",
                    "Parameters": {
                        "TaskId": "[OpenTasksList:Id]",
                        "Comment": "The purchase request was withdrawn.",
                        "OnError": []
                    }
                }
            ],
            "ContinueOnError": true,
            "OnError": []
        }
    }
]

With Continue on error checked, a task that can't be cancelled doesn't stop the loop.

3. List my overdue order tasks

This action lists the open Purchase order tasks assigned to the current user that the due-date job has marked overdue. [LateOrders:Ids] holds their ids.

{
    "Title": "Get Tasks",
    "ActionType": "PlantAnApp.Tasks.GetTasks",
    "Description": "List my late order tasks",
    "Condition": null,
    "Parameters": {
        "View": {
            "Expression": "",
            "Value": "AssignedToMe",
            "IsExpression": false,
            "Parameters": {}
        },
        "TaskType": "purchase-order",
        "OverdueOnly": true,
        "OutputToken": "LateOrders",
        "OnError": []
    }
}

Revised 11/12/2026