Escalate 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

Runs the task's next escalation step now, with a reason. It's the same workflow the due-date job would run at the step's time.

Typical Use Cases

• Let a buyer ask for help with an order task before it's late
• Let a Task administrator hand a stuck task to the next level straight away
• Add your own Escalate button, as the task panel of My Tasks has

Don't use it to

• Escalate tasks when they're late. The due-date job runs the escalation steps at their times by itself. See Due Dates, Escalation and Events.
• Change the assignee or the priority directly. Use Reassign Task or Update Task instead.

Related Actions

Action Name	Description
Read Task	Reads a task, with whether the current user may escalate it and what Escalate would run.
Reassign Task	Sets a new assignee, new candidate roles, or both.
Update Task	Changes the title, description, priority or due date.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Task Id	The id of the task, usually a token such as [Id] in a grid row.	Yes	empty	Yes
Reason	Why the task is escalated. At most 2000 characters. The step's workflow gets it as [Comment], and so does the workflow the type binds to Escalated.	Yes	empty	Yes
Output Token Name	The name of a token, without brackets, that receives the task after the step ran, for example Task. See Task fields in tokens.	No	empty	No
On Error	Actions to run when the escalation is refused or its step fails. [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>:EscalationStep], [<Output Token Name>:EscalatedOn] and the other fields	The task after the step ran, with the number of the step and when it ran. The step's workflow may have changed the task too. See Task fields in tokens.

Considerations

• Who may escalate. The Task administrators of the type and superusers always may. The assignee may when the type has The assignee can escalate on, which it is by default. An escalation step's workflow acts as the system, which may escalate too.
• The step counts as done. The due-date job doesn't run it again, and later steps keep their times, counted from the due date. When the last step repeats, each escalation runs it once more.
• Without a due date. A task without a due date has no step times, but it can still be escalated, one step at a time.
• How the step runs. The step's workflow runs as the system, before the action finishes. It gets [Reason] as manual, [EscalatedBy] as the user id of the person who escalated, [Comment] as the reason, and [EscalationNote], a sentence that says who escalated the task and why. Then the type's Escalated workflow runs, with the reason manual.
• If the step's workflow fails, nothing is escalated and the step stays pending for its own time.

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

Message	Why
Write why you're escalating this task.	Reason is empty.
The reason can have at most 2000 characters.	Reason is too long.
Tasks of type <type> have no escalation steps.	The type has no escalation steps.
Every escalation step of this task has already run.	No step is left.
Only a Task administrator can escalate tasks of type <type>.	The assignee tried, and the type has The assignee can escalate off.
Only the assignee or a Task administrator can escalate this task.	The user is neither.
The escalation step could not run, so nothing was escalated. Try again later, or ask a Task administrator.	The step's workflow failed. Its error is in the log.

Examples

tip

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

1. An Ask for help button

Add this action to a button of a form with a TaskId field and a Why field. On a Purchase order task, it runs the type's next escalation step, for example "Purchase order - Hand over to the leads". If the task can't be escalated, the user sees why.

{
    "Title": "Escalate Task",
    "ActionType": "PlantAnApp.Tasks.EscalateTask",
    "Description": "Ask for help with the task",
    "Condition": null,
    "Parameters": {
        "TaskId": "[TaskId]",
        "Reason": "[Why]",
        "OutputToken": "Task",
        "OnError": [
            {
                "Title": "Display Error Message",
                "ActionType": "ShowError",
                "Parameters": {
                    "Message": "<p>[ExceptionMessage]</p>"
                }
            }
        ]
    }
}

Revised 11/12/2026