Retool Workflows blocks

Learn about the different blocks and functions you can use in workflows.

πŸŽ‰

beta

Retool Workflows is currently in public beta for Retool Cloud organizations. Sign up to get started β†’

Workflows are made up of blocks that are chained together to perform specific actions in sequential order. After a block has completed its action, it triggers the next block in the chain, and so on.

Each block can access data from other blocks that have already run, and some blocks can be reused or perform conditional actions.

Control flow

You connect blocks together to define their control flow, which represents the order of operation. The first block in every workflow is the Start block and the control flow is defined by the connecting line between blocks.

Retool Workflows Subscription BotRetool Workflows Subscription Bot

To connect blocks together, click and drag β¦Ώ from one block to another. The name of a connected block appears as a label on the left. Hover the cursor over this label to preview the incoming data. To disconnect a block, click and drag its label away from the block to which it's connected.

You can connect a block to multiple blocks to perform multiple actions with data, resulting in multiple control flows that run in parallel. This is useful if you want to update multiple data sources with the same data.

πŸ“˜

For complex conditional actions, use Loop, Branch, and Functions instead.

Each block can access data from any block that has previously run. Use query1.data in JavaScript code and {{ query1.data }} for all other queries.

return query1.data;
Select * from {{ query1.data }}

Any blocks that are not in the control flow (i.e., no connecting line) are not run automatically and display a warning triangle icon to reflect their lack of connection.
|

Start block

The Start block is the first block in a workflow and cannot be removed. This block is where you configure settings to trigger the workflow and run it automatically.

Configure the scheduleConfigure the schedule

Query blocks

πŸ“˜

Learn more about Retool's supported integrations and how to connect your own data sources.

Query blocks interact with your connected data sources. You can query databases using SQL statements, perform REST, GraphQL, or SOAP API requests, and write JavaScript to transform data and perform complex logic.

Query JSON with SQLQuery JSON with SQL

JavaScript is the primary method for manipulating and transforming data. You can run custom JavaScript in a Query block using the Run JS Code resource in either Script or REPL mode.

  • Script mode runs only when executed. It must include a return statement to output values.
  • REPL (Read Evaluate Print Loop) mode runs continuously as you write JavaScript code. It implicitly returns a value without needing a return statement.

You can build complex logic or manipulate data using JavaScript methods like map(). For example, you could transform an array of account records so that it confirms to the schema of the database table to which it is saved.

const data = getAccounts.data;

return data.map((account) => ({
  name: account.Name,
  account_number: account.AccountNumber,
  industry: account.Industry,
}));

In general, Retool recommends you visually construct conditional statements with Branch blocks or filter query results using Filter blocks.

πŸ“˜

Learn more about triggering queries with JavaScript.

Loop blocks

A Loop block iterates through an array of data and triggers an embedded Query block for each evaluated item. This is useful for automating repetitive actions or performing complex logic.

The Loop block contains an embedded Query block that triggers for each evaluated item. Use value and index to reference evaluated items and their indexes. For example, a renewal reminder for the data above can use values like {{ value.plan }}, {{ value.email }}, and {{ value.first_name }} to customize the email for each user.

The default mode for Loop blocks is GUI. This mode automatically configures the loop to iterate through the query data you select from the Iterable dropdown.

Loop through data and trigger queryLoop through data and trigger query

If you require more complexity with your loop logic, use Code. This mode allows you to configure the JavaScript code used by the Loop block. You must specify the query data through which to loop within the custom code.

Loop through data and trigger query with custom codeLoop through data and trigger query with custom code

Branch blocks

Instead of writing if...else statements in JavaScript, you can use Branch blocks to visually build conditional statements that control different connected blocks. This is useful for breaking out complex JavaScript logic into more manageable blocks.

A Branch block evaluates the data it receives from a connected block using the defined condition. If the condition evaluates as a truthy value, the workflow follows the control flow for the If statement. If not, it follows the control flow for the Else statement. For example, you could build a workflow that alerts your Security team if the number of declined orders exceeds 25% of all received orders.

(100 / getTotalOrders.data.length) * getDeclinedOrders.data.length >= 25;

You can add multiple branches as Else if statements and visually build out complex conditional logic. As you test your workflow, the condition that evaluates as true is highlighted in green.

Each conditional statement has its own connector so you can connect different blocks and define separate control flows for each outcome.

Filter blocks

🚧

Optimize your queries to filter data and return only the results you need first (e.g., use LIMIT or WHERE clauses).

If you need a workflow to perform actions with only a specific subset of data, use Filter blocks to return results only if they meet certain conditions. If an item evaluates as true, the Filter block includes it in the data it returns.

Filter blocks function similar to Loop blocks and iterate through the query you select from the Iterable dropdown. Set the Filter Expression to a condition that should evaluate as true, using value and index to reference evaluated items and their indexes.

For example, you can use a Filter block to return a list of subscriptions that are due to expire within the next 24 hours using the expression moment(value.expires).isBetween(moment.now(), moment().add(1, 'day')).

Filter query dataFilter query data

Functions

Functions are reusable blocks that run queries in a headless state. They operate outside of the control flow and do not appear on the canvas. You call Function blocks from JavaScript queries and can pass data as parameters. This reduces the need for query duplication and enables you to perform certain tasks only when necessary, not for every workflow run.

Create a functionCreate a function

Add a function

To create a Function block, click + in the Functions section of the left panel. You can configure optional parameters for each block that you can reference within the block itself. Each parameter must have a test value so it can perform a test run without being called.

You can also create Function blocks directly from a block's code editor. Type / on a new line and enter the name of a resource, then press Enter. You can also reference an existing function in the same way by entering the name of an existing function.

πŸ“˜

The resource name refers to the name used by your Retool organization (e.g., onboarding_db), not the name of the service used (e.g., PostgreSQL).

You call a Function block using await and include values for each parameter, if set. For example:

const subs = getExpiringSubscriptions.data;
const message =
  workflowContext.name +
  ": You have " +
  subs.length +
  " subscription(s) expiring this week!";

await sendMessage(message);

Call a functionCall a function

The Function block returns its output back to the Query block from which it was called, allowing it to be used in the rest of the workflow.

Add and connect blocks

There are two methods for adding and connecting blocks:

  • Click and drag β¦Ώ from an existing block. This automatically creates a connection between blocks.
  • Click + in the toolbar to add a block. You must then click-and-drag β¦Ώ from one block to another.

You can use either method to add blocks to your workflow and connect them together.

Duplicate a block

Click β«Ά and select Duplicate to create a copy of an existing block.

Duplicate a blockDuplicate a block

Block settings

You can configure a number of settings for blocks. The settings available depend on the type of block and resource currently in use. Click β«Ά in a block to open its settings menu.

Available settings include:

  • Use the block as an error handler.
  • Format code syntax. You can also press Ctrl L to format code.
  • Switch SQL queries between raw SQL and GUI mode.
  • Set a timeout (in ms). Query blocks can have a maximum timeout of two minutes (120000).
  • Duplicate or delete a block.