Automate Group Membership using Retool API

This lab focuses on the use of Retool User attributes, Retool Events, Retool Workflows and Retool Platform API to demonstrate developing automated user processes. In this example a user creation event will trigger a workflow to add that user to a pre-existing group. This will help admin’s think about additional automations they can create to improve onboarding processes or other capabilities exposed by the Retool API.

Requirements

This lab requires that you are able to generate a Retool API Token to access the Retool API and an enterprise license.

Steps

Create Retool API Token

To provide the appropriate access to Retool API, a token is required.

• Select Settings > API.
• Specify a token name, description and select the scopes that you need, for this example we need Read, Write for Users and Read, Write for Groups.

• This will present a one-time window with the key that you need to copy the value from.

• The key will then be seen under Access Tokens.

Create Retool API Resource

To start the process, we first need to create a Retool API Resource that can be used within Retool Workflows.

• Create new > Resource > OpenAPI
• Specify a Name, Description, Specification URL, Authentication and Bearer Token.
  • Name = Retool API Resource
  • Description = Access Retool API for user/group events.
  • URL = https://<retool domain>/api/v2/spec
  • Authentication = Bearer Token
  • Bearer Token = Token value from the previous step.
• Select Test connection to confirm.

• Select Save changes to save the Resource.

Create User attribute

User attributes provide a way of adding additional meta-data to a user.

• Create a user attribute by going to Settings > User attributes > Create attribute.
• Provide a name, description, data type and default value.
  • Name = team
  • Description = which team
  • Data type = String
  • Default value = none

Create Permissions Group

In order to add a user to a group, we need to have an existing group. For this lab, we will create a group named education.

• Go to Settings > Permissions > Create new.
• Enter a group name of education and select Create group.

Create Workflows

The Add Member to Group workflow shown in the following figure focuses on the activities identified in the table.

Block Name	Block Type	Description
startTrigger Block (receive event)	Trigger	Initiates the workflow and receives a user event from Retool.
getUsersFromUserPool	Resource query	Queries the Retool API to get all users.
getUserEmail	Code (JavaScript)	Extracts the user id using received email.
addUserAttribute	Resource query	Updates user attribute using user id.
getGroups	Resource query	Retrieve all groups.
getGroupId	Code (JavaScript)	Extracts the group id searching for a specific group name.
addUsersToPermissionGroup	Resource query	Updates group with a member.
webhookReturn1	Response	Webhook response.

startTrigger

Go to Workflows > Create new > Workflow. The editor will appear as the following:

Modify the name of the Workflow to Add Member To Group by selecting the auto-generated name and editing. Close the Get started with Workflows dialog. In addition, delete the code1 block so that only the startTrigger remains as shown in the following figure.

Edit the startTrigger Test JSON Parameters to have the following payload:

{
	"createdUserEmail": "YOUR_EMAIL_HERE"
}

getUsersFromUserPool

Next we will query the Retool API User Pool using the Retool API Resource we created previously.

• Add a Resource Block either by select Blocks > Resource query or selecting the circle on the right side of startTrigger Add block > Resource query.
• Specify Retool API Resource with the following value:
  • Operation = GET /users

It will appear in the following figure.

getUsersEmail

Next we need to extract the user object using the email we receive in the startTrigger. This object will include the user id and this will be employed later in the workflow.

Create a Code block to the right of getUsersFromUserPool and connect them. Paste the following JavaScript into the Code block.

const arr = getUsersFromUserPool.data.data;
const found = arr.find((element) => element.email === startTrigger.data.createdUserEmail);
return found;

The workflow will now appear as follows:

addUserAttribute

Next we will update the user attribute, team, defined in the previous section.

• Create a Resource query block to the right of getUsersEmail and connect them.
• Specify Retool API Resource with the following value:
  • Operation = POST /users/{userId}/user_attributes
  • Path = {{getUserEmail.data.id}}
  • Request Body / value = development
  • Request Body / name = team

The following figure shows this block completed.

getGroups

Next we will update the user attribute, team, defined in the previous section.

• Create a Resource query block to the right of addUserAttribute and connect them.
• Specify Retool API Resource with the following value:
  • Operation = GET /groups

The following figure shows this block completed.

getGroupId

Next we need to extract the group id that matches a specific group name (e.g. education). This id is required to be able to add members.

Create a Code block to the right of getGroups and connect them. Paste the following JavaScript into the Code block.

let groupId = 0;

for (let i=0; i < getGroups.data.data.length; i++){
  if (getGroups.data.data[i].name == 'education'){
    groupId =  getGroups.data.data[i].id;
  }
}

return groupId;

The workflow will now appear as follows:

addUsersToPermissionGroup

Next we will place the user that was created as a member into the education permission group.

• Create a Resource query block to the right of getGroupId and connect them.
• Specify Retool API Resource with the following value:
  • Operation = POST /groups/{groupId}/members
  • Path = {{getGroupId.data}}
  • Request Body / members / is_group_admin = false
  • Request Body / members / id = {{getUserEmail.data.id}}

The workflow will now appear as follows:

webHook1

We finalize the workflow by creating a Response block to the right of addUsersToPermissionGroup and connect them.

Update Retool Event to use Workflows

Once the workflow is complete, we need to connect it to User Events. As events are generated, registered workflows will get initated.

• Go to Settings > Retool Events > User create.
• Select the Add Member To Group workflow.

Create User

To now simulate the entire process, it is necessary to create a user. This will require a unique email address or you can leverage Gmail. For example for the following email address, you can create new addresses:

• Original email: test123@gmail.com
• New email: test123+user1@gmail.com
• Another new email: test123+user2@gmail.com

Each of these will forward email to the original address but is treated unique within Retool for login purposes.

• Go to Settings > Users > Create new and specify a user name. This new user should trigger the workflow where the user will get a user attribute and will then be added to the developer permissions group.
• You can confirm this by going to Workflows > Run history to see if the workflow was triggered and each step that it executed.
• In addition you can confirm the user attribute has been updated as shown in the following figure.

• Finally we confirm the user has been added as a member to the group, education.