Create 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

Creates a task for a user or for the members of candidate roles, with a type, a due date and the record it's about. The task appears in their My Tasks.

Typical Use Cases

• Ask the Buyers to check the supplier of a purchase request, attached to the request so the task shows on the request's Tasks tab
• Give the requester a task to confirm the delivery once the order is placed
• Create a task from a form that has no record, for example a request sent through a contact form
• Create the task that a BPMN 2.0 user task waits for

Don't use it to

• Create the same tasks every time a record enters a lifecycle state. Use a checklist on the state instead. It creates the tasks when the record enters the state and handles the open ones when it leaves.
• Wait in a workflow until someone completes the task. This action doesn't wait. In a BPMN 2.0 workflow, use a user task.
• Remind people of a task that's late. Use the task type's escalation steps.

Related Actions

Action Name	Description
Assign Task	Sets the assignee of a task.
Reassign Task	Sets a new assignee, new candidate roles, or both.
Update Task	Changes the title, description, priority or due date.
Complete Task	Completes a task with an outcome.
Cancel Task	Cancels an open task.
Get Tasks	Lists tasks, for example the ones attached to a record.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Task Type	The task type. It sets the outcomes, who gets the task by default, the due rule and the escalation steps. Pick it from the list, or switch to an expression and give its key or name, for example purchase-check. When it's empty, the task is of the built-in type General.	Yes, as an expression	General	No
Title	What has to be done, for example Check the supplier of [Title]. At most 450 characters.	Yes	empty	Yes
Description	Details for the person doing the task. The task panel of My Tasks shows them.	Yes	empty	No
Assignee	The user who must do the task: a user id, username or email, for example [User:UserID]. Leave it empty to give the task to its candidate roles, for one of their members to assign to themselves.	Yes	empty	See Who gets the task
Candidate Roles	The roles whose members can take the task while it's unassigned. Pick roles from the list, or switch to an expression and give role names or ids separated by commas, for example Buyers. When it's empty, the task type's candidate roles are used if the type has any.	Yes, as an expression	empty	See Who gets the task
Due Date	When the task is due. Pick a date and time. It overrides the due rule of the task type.	No	empty	No
Due Date (Text)	A date or a token, for example [DateTime:Relative(add="2 days")|o]. It's used when Due Date is empty.	Yes	empty	No
Priority	Low, Normal, High or Urgent. Switch to an expression to set it from a token.	Yes, as an expression	Normal	No
Attach To	The relation that links the task to a record, shown as the entity and the relation, for example Purchase Request › Tasks. The list shows the relations from your entities to Task. To add one, add a List of Tasks property to the entity.	Yes, as an expression	empty	No
Record Id	The id of the record to attach the task to, for example [PurchaseRequestId].	Yes	empty	With Attach To
Output Token Name	The name of a token, without brackets, that receives the new task, for example NewTask. See Output.	No	empty	No
On Error	Actions to run when the task can't be created. [ExceptionMessage] holds the reason. See Errors and refusals.	No	empty	No

Output

Token	Description
[<Output Token Name>]	The id of the new task.
[<Output Token Name>:Id], [<Output Token Name>:Title], [<Output Token Name>:DueDate] and the other fields	The new task's fields. See Task fields in tokens.

The tokens are only set when Output Token Name has a value.

Who gets the task

A task needs an assignee, at least one candidate role, or both:

• An assignee only. The task is assigned to that user straight away.
• Candidate roles only. The task is unassigned. Every member of the roles sees it under Unassigned in My Tasks, and one of them assigns it to themselves.
• Both. The task is assigned, and the candidate roles stay on it. The assignee can unassign it back to the roles, and delegate it to their members from My Tasks.

When Candidate Roles is empty and the type's Who gets the task is Candidate roles, the type's roles are used, also when the action gives an assignee. When neither the action nor the type gives an assignee or a role, the action fails with A task needs an assignee or at least one candidate role.

Considerations

• Anyone can create a task. No task right is checked, so a task can come from a public form too. The user who runs the action becomes the task's creator, who may cancel it. A task created in an escalation step's workflow has no creator. See Who may do what.
• The due date. Due Date comes first, then Due Date (Text), then the due rule of the task type, counted from now. Without any of them, the task has no due date, and its escalation steps never run on their own. A typed date without a time zone is read in the server's time zone.
• Attaching a record. The task is attached only when both Attach To and Record Id have a value. Attach the task to a record so it shows on the record's Tasks tab and in the task panel, and so Get Tasks can find the record's tasks.
• The Created event. The workflow the type binds to Created runs before the action finishes.
• Task types aren't exported with the application. A workflow that names a type by its key needs a type with the same key on the site you import it into.
• In a BPMN 2.0 user task. A user task holds exactly one Create Task action, which must have an Output Token Name. When the task is completed, the run continues, and the same tokens hold the completed task, with its outcome. For a cancelled task, see User Tasks.

The action can fail with these messages:

Message	Why
A task needs a title.	Title is empty, for example because its token is empty.
The title of a task can have at most 450 characters.	Title is too long.
There is no task type "<value>".	No task type has this key or name.
A task needs an assignee or at least one candidate role.	See Who gets the task.
User #<id> does not exist, so the task cannot be assigned to them.	Assignee is a user id that doesn't exist.
No user matches "<value>".	Assignee is a username or email that matches no user.
No role matches "<value>".	A role in Candidate Roles doesn't exist.
"<value>" is not a date.	Due Date (Text) isn't a date.
The priority must be Low, Normal, High or Urgent.	Priority has another value.
Attach to must be a relation from an entity to Task.	The expression in Attach To isn't a relation id.
Records can be attached to a task only through a relation from their entity to Task. Add one in the entity designer.	Attach To names a relation that doesn't lead to Task.
"<value>" is not a record id.	Record Id isn't a number.

Examples

tip

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

In these examples, [Title] and [PurchaseRequestId] hold the title and the id of a purchase request. After importing, pick Purchase Request › Tasks in Attach To, which replaces the placeholder relation id.

1. Ask the buyers to check the supplier

This action creates a Purchase check task for the Buyers, due in two days and attached to the purchase request. Any buyer can assign it to themselves from My Tasks. The new task's id is in [SupplierCheck].

{
    "Title": "Create Task",
    "ActionType": "PlantAnApp.Tasks.CreateTask",
    "Description": "Ask the buyers to check the supplier",
    "Condition": null,
    "Parameters": {
        "TaskType": {
            "Expression": "",
            "Value": "purchase-check",
            "IsExpression": false,
            "Parameters": {}
        },
        "Title": "Check the supplier of [Title]",
        "Description": "Check that the supplier is on the approved list and that the price is right.",
        "CandidateRoles": "Buyers",
        "DueDate": "[DateTime:Relative(add=\"2 days\")|o]",
        "AttachTo": {
            "Expression": "",
            "Value": "00000000-0000-0000-0000-000000000000",
            "IsExpression": false,
            "Parameters": {}
        },
        "AttachRecordId": "[PurchaseRequestId]",
        "OutputToken": "SupplierCheck",
        "OnError": []
    }
}

2. Give the requester a follow-up task

This action creates a Purchase follow-up task assigned to the requester, whose user id is in [RequesterId], with a high priority. The task type's due rule sets the due date. If the task can't be created, the reason is logged, and then the action fails.

{
    "Title": "Create Task",
    "ActionType": "PlantAnApp.Tasks.CreateTask",
    "Description": "Ask the requester to confirm the delivery",
    "Condition": null,
    "Parameters": {
        "TaskType": {
            "Expression": "",
            "Value": "purchase-follow-up",
            "IsExpression": false,
            "Parameters": {}
        },
        "Title": "Confirm the delivery of [Title]",
        "Assignee": "[RequesterId]",
        "Priority": {
            "Expression": "",
            "Value": "High",
            "IsExpression": false,
            "Parameters": {}
        },
        "AttachTo": {
            "Expression": "",
            "Value": "00000000-0000-0000-0000-000000000000",
            "IsExpression": false,
            "Parameters": {}
        },
        "AttachRecordId": "[PurchaseRequestId]",
        "OutputToken": "FollowUp",
        "OnError": [
            {
                "Title": "Log Error",
                "ActionType": "LogError",
                "Parameters": {
                    "Message": "The follow-up task for purchase request [PurchaseRequestId] wasn't created: [ExceptionMessage]"
                }
            }
        ]
    }
}

3. Create a General task from a contact form

This action creates a task of the built-in General type for the Employees role, from a form with Name and Message fields. There's no record to attach. General has one outcome, Done.

{
    "Title": "Create Task",
    "ActionType": "PlantAnApp.Tasks.CreateTask",
    "Description": "Ask someone to call back",
    "Condition": null,
    "Parameters": {
        "Title": "Call back [Name]",
        "Description": "[Message]",
        "CandidateRoles": "Employees",
        "DueDate": "[DateTime:Relative(add=\"1 days\")|o]",
        "OutputToken": "CallBack",
        "OnError": []
    }
}

Revised 11/12/2026