Reassign Task

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, Tokens, Workflows

A Task administrator sets a new assignee, new candidate roles, or both. With roles and no user, the task goes back to the pool of those roles.

Typical Use Cases

• Hand a late order task over to the Procurement Leads, in an escalation step's workflow
• Move a task to other roles when the work changes hands, for example from the Buyers to the Finance Controllers
• Give a task to one person and change its candidate roles at the same time

Don't use it to

• Take a task yourself. Use Assign Task to Current User instead.
• Hand on a task you're assigned. Use Delegate Task instead.

Related Actions

Action Name	Description
Assign Task	Sets the assignee and keeps the candidate roles.
Unassign Task	The assignee gives the task back to its candidate roles.
Update Task	Changes the title, description, priority or due date.
Escalate Task	Runs the task's next escalation step now.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Task Id	The id of the task, usually a token such as [Task] in an escalation or event workflow, or [Id] in a grid row.	Yes	empty	Yes
User	The new assignee: a user id, username or email.	Yes	empty	See What changes
Candidate Roles	The new candidate roles. Pick roles from the list, or switch to an expression and give role names or ids separated by commas, for example Procurement Leads. When it's empty, the roles don't change.	Yes, as an expression	empty	See What changes
Comment	Why the task is reassigned. The event workflows get it as [Comment]. It isn't saved on the task.	Yes	empty	No
Output Token Name	The name of a token, without brackets, that receives the task after the change, for example Task. See Task fields in tokens.	No	empty	No
On Error	Actions to run when the task can't be reassigned. [ExceptionMessage] holds the reason. See Errors and refusals.	No	empty	No

Output

Token	Description
[<Output Token Name>]	The id of the task.
[<Output Token Name>:Assignee], [<Output Token Name>:CandidateRoles] and the other fields	The task after the change. See Task fields in tokens.

What changes

User	Candidate Roles	Result
Set	Empty	The user becomes the assignee. The candidate roles stay as they are.
Empty	Set	The task goes back to the pool of the new roles: nobody is assigned, and an In progress task goes back to Open.
Set	Set	The user becomes the assignee, and the roles replace the candidate roles.
Empty	Empty	The action fails with Choose a user or candidate roles to reassign the task to.

If the task was delegated, it no longer shows who delegated it.

Considerations

• Who may reassign. The Task administrators of the task's type, superusers, and escalation steps' workflows, which act as the system. In My Tasks, Task administrators use Reassign in the task panel.
• Any user. The new assignee doesn't have to be a member of the candidate roles.
• The Assigned event. The workflow the type binds to Assigned runs with the reason reassign, the previous assignee and the comment. A notification workflow can use it to tell both the old and the new assignee.

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

Message	Why
Only a Task administrator of <type> can reassign this task.	The user running the action isn't a Task administrator of the type.
Choose a user or candidate roles to reassign the task to.	User and Candidate Roles are both empty.
No user matches "<value>".	User is a username or email that matches no user.
User #<id> does not exist.	User is a user id that doesn't exist.
No role matches "<value>".	A role in Candidate Roles doesn't exist.

Examples

tip

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

1. Hand a late order task over to the leads

Add this action to a workflow that implements the Task Escalation contract, such as "Purchase order - Hand over to the leads", and use it as an escalation step of the Purchase order type. [Task] holds the id of the late task, and [Step] the number of the step. The task goes back to the pool of the Procurement Leads, whoever had it.

{
    "Title": "Reassign Task",
    "ActionType": "PlantAnApp.Tasks.ReassignTask",
    "Description": "Hand the order over to the procurement leads",
    "Condition": null,
    "Parameters": {
        "TaskId": "[Task]",
        "User": "",
        "CandidateRoles": "Procurement Leads",
        "Comment": "Escalation step [Step]: the order wasn't placed in time, so it's handed over to the procurement leads.",
        "OnError": []
    }
}

To raise the priority at the same step, add Update Task after it.

2. Give a task to a finance controller

Add this action to a button of a form for Task administrators, with TaskId and Controller fields. The task is assigned to the chosen user, and the Finance Controllers become its candidate roles, so the user can unassign it back to them.

{
    "Title": "Reassign Task",
    "ActionType": "PlantAnApp.Tasks.ReassignTask",
    "Description": "Give the task to a finance controller",
    "Condition": null,
    "Parameters": {
        "TaskId": "[TaskId]",
        "User": "[Controller]",
        "CandidateRoles": "Finance Controllers",
        "Comment": "Moved to finance by [User:DisplayName]",
        "OutputToken": "Task",
        "OnError": [
            {
                "Title": "Display Error Message",
                "ActionType": "ShowError",
                "Parameters": {
                    "Message": "<p>[ExceptionMessage]</p>"
                }
            }
        ]
    }
}

Revised 11/12/2026