Skip to main content

Retool Workflows tutorial

A hands-on introduction to Retool Workflows.

Retool Workflows enables you to build, schedule, and monitor jobs, alerts, and ETL tasks. You can automate processes without the need for user interaction and take action based on conditions.

This guide explains how to build a workflow that performs a daily check for a new Stable release of Self-hosted Retool. If there's a new release, the workflow sends a notification using Retool Email. You can also trigger the workflow to check at any time with a webhook event.

1. Create a new workflow​

Sign in to your Retool organization, select the Workflows tab in the navigation bar, then click Create new > Workflow.

Create a new workflow

A workflow's name is initially set using the name of the current user and the creation date. Click the name of this workflow in the toolbar and set it to Subscribe to the Retool Changelog.

2. Configure triggers​

You can trigger workflows on a schedule or by sending a webhook event. This workflow uses two triggers:

  • A schedule trigger to run every 24 hours.
  • A webhook trigger to manually run the workflow. This allows you to run the workflow at any time and override the workflow to check for posts in a period longer than 24 hours.

Workflows can read the contents of a webhook event payload. You can specify test JSON parameters to function as default values, but which are overridden if provided by a webhook event.

Click in the left panel to open the Triggers tab.

Create schedule​

First, click + and add a Schedule trigger and configure it to run every day at 12AM, then click Create. You must then enable the schedule trigger.

Configure webhooks​

Next, add the Webhook trigger.

3. Fetch release notes​

Workflows are comprised of blocks that perform specific actions, such as interacting with data or performing custom logic. You connect blocks together to define their control flow, which represents the order of operation in which they run.

The Resource query block enables you to interact with APIs and databases. You would primarily use this to query resources—data sources you've connected to Retool—but you can also use it to interact with APIs and fetch JSON data with the RESTQuery resource.

Click and drag from the startTrigger block to create a new block, then select the Resource query block type. Click on the block name and change it to fetchPosts.

Retool publishes release notes for Self-hosted Retool. A JSON feed of the Retool Changelog is available and can be used to subscribe to notifications. The Changelog uses tags to filter different types of posts which are included in the JSON feed.

First, select the RESTQuery resource and the GET action type, then specify the JSON feed in the URL field.

JSON feed
https://docs.retool.com/changelog/feed.json

Click Run to retrieve the JSON feed data. The JSON feed contains an array of objects, items, that contains information about each release.

Next, add a JavaScript Code block that returns only the array of changelog items with fetchPosts.data.items. The workflow can now filter the results with a Filter block, which only passes along items if they match a certain condition. Each item contains a tag array of strings, so set the condition to value.tags.includes('Self-hosted').

4. Check the latest release notes​

Since this workflow will run daily, it only needs to use data from the most recently published release notes. All items in the JSON feed are published in reverse chronological order, based on date_modified. As such, you can reference filter1.data.items[0] for the most recent release notes.

You use the Branch block to perform different actions based on whether the input value meets a truthy condition. Branch blocks allow you to create two different paths for a workflow to take, depending on whether the condition evaluates as true or false. In this case, the workflow needs to check if the most recent release notes were published in the past 24 hours. To ensure that you can test the workflow even if there wasn't an update in the past 24 hours, this workflow uses test JSON parameters.

First, click and drag from filter1 to add a Branch block, then rename it to isNewPost. In the If statement, specify the following condition:

isNewPost
moment(filter1.data[0].date_modified).isSameOrAfter(moment().subtract(startTrigger.data.days, 'days'))

Next, update the Test JSON parameters in the startTrigger block to set a default value that can be overridden.

{"days" : 1 }

This value is used to check whether the most recent release notes were published within this time period. You can override this to fully test the workflow.

5. Summarize changes using AI​

You can leverage AI in workflows to perform actions, such as generating text. This workflow uses an AI action to generate a summary of changes, grouped by type.

Click and drag from the If statement in isNewPost to add an AI action block, then rename it to summarizeChanges. Select the Generate text action and instruct the AI model to generate a summary.

Instructions
{{filter1.data[0].content_html}} contains release notes for Self-hosted Retool.

Count the total number of changes, then a count of changes by type.

6. Send an email notification​

You can connect many communication platforms and services to Retool, such as Slack, Twilio, SendGrid, and Microsoft Teams.

The final action that the workflow must perform is to send an email with:

  • The Self-hosted Retool version number.
  • A link to the release notes.
  • The AI-generated summary.

You can use Retool Email to send emails without any extra configuration. Click and drag from the AI action block to add a new Resource query block, then rename it to sendEmail. Configure the block with the following values:

PropertyValue
ToThe email address to receive the notification.
Subject{{ filter1.data[0].title }} has been released

Finally, set Body to Markdown mode, then include the summary and release notes URL:

Message body
{{ summarizeChanges.data }}

---

{{ filter1.data[0].url }}

7. Test the workflow​

Workflows without a Response block respond immediately to confirm that the workflow started.

A new version of Self-hosted Retool is published every two weeks, so it's likely that the publication date for the most recent release notes won't be within 24 hours. To test the workflow end-to-end, use the webhook trigger and provide a custom value for days, specified earlier.

Open the Triggers tab and select the Webhook trigger. Click Copy > Copy as cURL to copy a cURL command to run in the CLI.

Copy a webhook cURL command

The command includes test JSON parameters—change the value for days to 30.

curl -X POST --url "https://api.retool.com/v1/workflows/090bb051-1534-4279-b863-35gfk8223/startTrigger" \
--data '{"days":30}' \
-H 'Content-Type: application/json' \
-H 'X-Workflow-Api-Key: retool_wk_xxxxxxxx'

Run the command to trigger the workflow.

8. Deploy workflow​

Now that the workflow is able to perform all required actions, you can manually run it to test. Click Run in the toolbar to run the workflow.

Workflows run automatically once deployed. If you want to test the schedule trigger and receive notifications automatically, click Deploy in the toolbar.