Skip to main content
This page is unlisted and can only be accessed directly via URL. It is excluded from the site navigation and search results.

Add user-driven steps, tasks, and approvals to workflows

User Tasks enable you to build workflows that require a user to take action before the workflow proceeds. The User Task block pauses a workflow and creates a user task within the organization. Users then review and action tasks using Retool apps. Only when a user submits task completion using a Retool app does the workflow containing the user task block resume.

Workflows containing a User Task block provide context data for a user task which is accessible from the Retool app. When actioned, the user task can provide output data back to the workflow.

Create user tasks from a workflow​

User groups assigned to a user task must also have use access to the associated app where the user tasks are exposed to users. If not, users cannot use the app to complete user tasks.

To create user tasks, add the User Task block to the control flow of a workflow. You then configure the following block fields:

SettingDescription
Assign ToThe users or groups that can action user tasks created by this workflow.
AppThe Retool app with which to review and action tasks.
Task ContextAdditional data from the workflow to include with the user task.
Expiry Time (days)The length of time after which the task expires.

The User Task block.

All user tasks initially have status of pending. This changes to submitted once a user actions the task. When the User Task block runs, no further blocks along the control flow run until the task is actioned.

Set user task assignments​

User task permissions are optional. If unset, any user in the organization can view and action the user task.

You can specify which users and permission groups are allowed to action tasks created by the User Task block. This is useful for restricting processes to a particular set of users, such as only allowing the finance team to administer refund requests.

Select a user or permission group.

You can also dynamically assign user tasks to users and groups using conditional logic. Click for the Assignments field and then specify custom JavaScript logic to dynamically evaluate assignments.

If your organization uses Source Control and has multiple instances of self-hosted Retool, ensure that user emails and group names are the same across instances.

When dynamically assigning tasks, the Assignments field expects an assignment object with the following properties.

email​

string

The email address.

name​

string

The user name.

type​

enum

The assignment type.

Values
user

The user to assign.

group

The group to assign.

The retoolContext global object contains groups and users properties with the necessary information.

if (getCaseload.data >= 5) {
  return retoolContext.users['jenny@example.com']
} else {
  return retoolContext.users['admin@example.com']
}

Dynamically assign users or permission groups.

You can also use a combination of users and groups when determining assignment.

Group and user assigmment
if (getCaseload.data >= 5) {
  return [retoolContext.users['jenny@example.com'], retoolContext.groups['Operations']]
} else {
  return [retoolContext.users['admin@example.com'],retoolContext.groups['Escalation Team'] 
}

Create the user tasks app​

Workflows that create user tasks and their associated apps must both use the same permission groups. If not, users cannot use the app to action user tasks.

You create a Retool app from the User Task block for users to action tasks. Once you add a User Task block, click Create User Task to create a task review app using the default template. This starter app includes basic functionality for managing user tasks. If you have Edit or Own permissions to app folders, you can create your app within any of those folders. The app inherits any folder-level permissions, if set.

You can run the User Task block as you build and test your workflow. When manually run, the Workflow:

  • Displays a modal in the Workflows IDE that contains the Retool app.
  • Creates a test user task for testing the workflow and app whilst it runs.
Starter app for user tasks

Provide task context​

The User Task block can include additional data to use as context for the user task (e.g., order details). You can reference this data within Retool apps from a task's context.result.data property to populate component values, reference in queries, etc.

Task context is evaluated as JavaScript and must either reference or return a valid value (e.g., startTrigger.data).

Set task expiration​

Use the Expiry Time field to specify length of time, in days, after which the task automatically expires. If no value is provided, the task does not expire. When a task expires, its status automatically updates to expired. Use integer or float numbers to specify the duration, such as 1 or 1.5.

After the task runs, you can reference the expiryMetadata property of the User Task block to reference expiration details. For example, to send a time-sensitive notification. expiryMetadata is an object with the following properties.

endDateEpochMs​

number

The end date, in milliseconds since the UNIX epoch.

expiryTimeMs​

number

The time, in milliseconds, until expiration.

type​

The expiration type.

Within an app, you can reference a task's expiresAt property to retrieve expiration details.

Specify task admins​

Users in the permission groups you select can review and action tasks using the Retool app. You can optionally specify Task admin permission groups in the block's Settings which allow those users to manage the tasks in the Tasks Console.

Send new task notifications​

The User Task block includes an additional connection to trigger another block when it creates a user task. Click and select a block to use. For example, you could add a Resource query block to send messages using Retool Email, Slack, etc.

When the User Task block creates a task, it generates a direct URL for the Retool app with a reference to a unique task ID in a URL parameter. You can reference the taskURL property when sending notifications so that users can navigate directly to app and view the newly created task.

Send a Slack notification when a new task is created.

Review and action user tasks from an app​

Retool organizations on the Enterprise plan can use the Retool API to programmatically manage tasks.

The starter app you create from the User Task block includes basic functionality for reviewing and actioning user tasks. You can modify the starter app based on your needs.

Write queries to interact with user tasks​

Queries interact with user tasks within Retool apps. The user tasks app created by the workflow is preloaded with queries to get user tasks created by the workflow, get details of a specific task, and mark the user task as submitted.

The starter app includes getUserTasks, getSingleUserTask, and submitUserTask queries for you to use. To create these queries yourself:

  1. Open the Code tab.
  2. Create a Resource query.
  3. Select the User Action resource.
  4. Select the User Task type.

There are three actions from which you can choose when querying user tasks.

The Get All User Tasks action retrieves a list of all user tasks for which the current user has access. You can specify the following options:

OptionDescription
WorkflowThe workflow that created the user task.
User taskThe name of the User Task block within the workflow. A workflow can create user tasks using multiple User Task blocks.
StatusThe task status.
Created AfterUser tasks created after the specified date.
Created BeforeUser tasks created before the specified date
Submitted AfterUser tasks actioned as submitted after the specified date.
Submitted BeforeUser tasks actioned as submitted before the specified date.
Next TokenThe next token from the previous API response. This is used for pagination for an arbitrary number of tasks.

Task context and output​

Each user task has state. A user task's context property contains the information provided by the workflow, such as the task context, which you can reference anywhere in the app.

The Complete User Task action includes an optional output that is saved to output. This data is passed back to the workflow to use as it resumes.

You can build workflows with conditional logic that perform different actions based on this output. For example, you can use the Branch block to determine whether to reimburse an expense based on whether the output contains "approved": true or "approved": false.

Manage tasks with the Tasks Console​

The Tasks Console cannot be used to action user tasks. Use a Retool app to review and action user tasks.

The Tasks tab of the organization contains the Tasks Console. From here, users can search for tasks, view task details, change the assigned permission group, or cancel tasks.

Admins can view all tasks across the organization. Task admins—users in permission groups specified in the User Task block settings—can only view tasks for which they are designated as task admins. All other users cannot access the Tasks Console.

User Tasks Console

View task information​

The Tasks Console displays a table of all user tasks. Each column corresponds to a property of the User Task object. To view more details about a specific task, click > to expand the row.

Cancel a task​

User tasks are initially created with a pending status. Tasks that are no longer required can be canceled by clicking Cancel Task.

Reassign a task​

Click Reassign Task to change the permission groups for a specific user task. As with User Task block permissions, you can select users and permission groups from a list or dynamically assign them.

User task storage for self-hosted deployments​

Retool stores all data related to user tasks, including user task context and outputs, in your deployment's externalized postgres database.