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 is currently in private beta. You can join the waitlist for early access.

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
PermissionsThe user 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.

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 permissions​

You can specify which user 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.

If you do not specify any permission groups, any user in the organization can view and action the user task.

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).

Provide data for task context

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.

Configure task admins

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 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. You can reference the taskURL property when sending notifications so that users can navigate directly to app and view the newly created task.

Trigger user task notifications

Review and action user tasks from an app​

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.

Task input 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—can only view tasks for their permission groups. 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.

User task storage for self-hosted deployments​

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