Create functions to reuse queries and logic in workflows

Learn how to create reusable queries or logic in a workflow.

Functions v2 is currently in private beta on Retool Cloud and Self-hosted Retool 3.114 or later.

Functions enable you to create reusable queries or complex logic. You can call functions anywhere in a workflow as function blocks, using JavaScript, or within a Loop block. Functions support optional parameters and have access to the global workflow scope.

Single-step and multi-step functions

You can choose whether a function is single-step or multi-step. The type you choose depends on the complexity or functionality required.

• Single-step: The function contains a single query that runs when called. Single-step functions are useful for simple logic, such as retrieving database records or transforming results.
• Multi-step: The function operates as a self-contained workflow. It has its own control flow and is assembled in the same way as a regular workflow. It supports all available block types, including logic and response blocks, for complex operations.

1. Add a function

First, click Functions in the left panel, then create a function. Then, configure the function.

1. Define any optional parameters to pass into a function when called. Click + Add parameter and set the parameter name. You can optionally provide a test value that is used only when the parameter is tested.
2. Select whether to use a single-step or multi-step function type.

Changing a function from multi-step to single-step permanently deletes the multi-step function logic.

2. Configure function logic

Single-step

The Query section contains the query or code that runs when the function is called. You can select a resource to query, Run JS Code or Run Python Code to execute JavaScript or Python code, or Retool Workflow to trigger another workflow.

For example, you could create a function that sends a trial expiration notification to customers when the trial is three days and one day from expiration. Instead of adding two separate blocks to send emails, you can create a single function and reuse it. The workflow first filters the customer data to determine which trials expire in 24 hours or in three days, then calls the same function. The function receives the customer's name and email address as parameters, along with either tomorrow or the trial expiration date.

Configure the resource or code that the function runs when called.

Multi-step

A multi-step function has its own blocks and control flow. Click Edit function to edit the function and assemble its blocks. You can also call other functions from within multi-step functions.

When you edit the function, the canvas switches to Function mode so you can assemble the function's blocks directly on the canvas. When in this mode, the canvas background is blue. Click Return to workflow at any time to go back to the workflow.

For example, you could create a function that sends a trial expiration notification to customers when the trial is three days and one day from expiration. In the single-step function example, the workflow contained the logic to determine which trials expired in 24 hours and in three days. With a multi-step function, the workflow can be streamlined by offloading the logic to the function.

A multi-step function with branched logic.

The customer data is passed as the function parameter, and the multi-step workflow handles the remaining logic. Since there is already a single-step function to send emails, the multi-step function can reference it in the same way as the workflow. As a result, the workflow only needs to call the multi-step function after retrieving the customer data.

Logs for multi-step functions are available in the Run history panel. These block-level logs are nested under whichever block or loop iteration called the function.

4. Test the function

Click ▶︎ Test to run the function. If your function makes use of parameters, any test values you provided are used.

5. Call the function from the workflow

You can call a function using the following methods:

• Using the Function block to the workflow.
• Within a JavaScript Code block.
• As the loop runner for a Loop block.

Function block

Click in the left panel to open the Blocks tab, then drag the Function block type to the canvas. You can also right-click anywhere on the canvas to display the Add block contextual menu.

If you defined any parameters for the selected function, the block displays input fields for you to populate. You can then reference any data using {{ }} expressions, such as {{ getCustomersOnTrial.data }}.

A streamlined workflow using a multi-step function.

JavaScript Code block

You can call a function from a JavaScript Code block using await and the function name. For example:

const email = getUsers.data[0].email;
const name = getUsers.data[0].name;

await function1(name, email);

Loop block

Loop blocks can call a function so that it is used for every loop iteration. Set the Loop runner to the desired function and use {{value}} or {{index}} to reference evaluated items in parameters.

A Loop block that calls a function.

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

Convert a group of blocks to a multi-step function

You can convert a group of blocks within an existing workflow to a multi-step function. First, press and hold shift while click-and-dragging on the canvas to select a group of blocks. Next, right-click on the selection area and click Create function.

Convert a group of blocks to a function.

The selected blocks are then replaced in the workflow by a Function block that references the newly created function.