Call me an entomophobe, but don’t we all hate a bug. And one pesky side-effect of technical bugs is the panic that ensues when a toast message starts buzzing around the top of a non-technical user’s Retool app. While - depending on the resource - these error messages give failure responses aimed at developers, and not at the technically-spooked.
That’s why in this tutorial we will show you how to make a bug reporting modal, which automatically pulls in the payload of a failed query, allows users to augment the error report and provide a narrative of how it happened, and shoots a detailed summary task onto your Bug Reporter Tool without leaving your Retool Application. This avoids users needing to understand and interpret the message that appears (and very quickly disappears), and helps to stop them from performing this buggy action twice - just to catch a screenshot of the message - and really screw something up.
Keep following for a tutorial on how to create this quick-and-easy integrated bug report modal, but also for some simple Asana integration in Retool.
The first thing you’re going to do is create a temp state to house your error data, by clicking ‘Create new’ under ‘Temporary State’ in the left-hand column. This temporary state variable will be initialized by a failed query and house the error payload that is returned by the resource.
Name this something like ‘errorLog’ (you do this in the right-hand ‘Inspect’ column).
Next, we'll perform a single script inside of an event handler to initialize our errorLog and open our error Modal on failure:
As you can see here, on failure of this query the modal will open and the temporary state will be set to (self), the resource’s response to the failed query. Test this is working by causing your query to fail on purpose (a quick way is linking to a Google Sheet that doesn’t exist).
You should see an object like this in the temp state:
You are now going to connect this modal to some of the error data in your temp state so that your user can submit a detailed report, and understand a little about what is going on.
Pull in a text box for the title of the Bug Report, and then a form with another text box for the error information. Then, add a text input area so that users can type in some further details (you should set an explanatory placeholder to aid UX).
This is how it should look when done:
To include this data, your text component value will look like this:
The first bit of code pulls in the name of the app from Retool’s context attribute. The second line pulls in the current user’s email, so a developer can contact them for more info. The errored query, error type, message and code are all pulling data in from the errorLog temp state for your developer.
Note that there may be no error type (which sometimes returns the value ‘true’ rather than an explanation) nor error code for certain queries, so for these we used a ternary to return ‘N/A’ instead. It’s best to test these values with all the queries available in your app, as the results in the error log may vary.
Once again, make sure to test this is all working correctly by purposefully failing a (non-critical!) query.
To set up the rest of the bug modal, you’ll need to connect your app to the project where your team reads Bug Reports. We will be using Asana for this tutorial, however a similar pattern will work with Linear, Jira, monday.com, or any other task management system with an API. Since Asana is an integrated resource in Retool, this is super easy.
You can follow along with the Asana side and find more API references in their documentation.
Retool provides extra documentation for Linear, as well as for Jira.
If you don’t have Asana connected already, create a new query and head to ‘Create a new resource’:
Select Asana from the list,
And then all you need to do is give it a name and click ‘Test OAuth…’ to log in through Asana!
Once you are logged in, you’ll have access to a list of preset API calls through the ‘operation’ drop-down:
For this tutorial, you will need your workplace ID, the project ID of the Asana board you’d like to send the bug report to, and the ID of the section in this project (if it isn’t the first, left-hand one).
You can find these in your Asana account, in the URLs of the workspace page/project etc, but another easy way to find them without leaving Retool is using a couple of GET queries to pull this info in, namely:
GET/workspaces, which will return your workspace name and gid:
GET/projects, which will return the project names and gids:
And finally GET sections, where you will reference the relevant project gid from the previous getProjects query to pull in the sections available on that project (this info is harder to find in Asana):
It’s a good idea to copy and paste these gids for the next queries, rather than referencing them through the query, as the reference index number of each can change depending on the developer using the app.
Now that you have all the relevant gids, you can create a POST /tasks query to create a new task in the correct project.
This is how ours looked:
In the data.workspace parameter and in the data.projects parameter, we have inserted the gid of the workspace and project to which we’d like to post the task, with the project in brackets to be an array.
For the data.name parameter, we are setting the name of the task, i.e. the title on the task card. For clarity, as these ‘tasks’ will work as tickets for the developer, we have included the Retool app name, the error message and the current user.
When you click run, this should create an Asana task like this:
In this case, the task is automatically posted to the first (or left-hand) section of the project. If you wish to define a section to add this to (e.g. a Retool specific one) there are two ways: there is an option to define the sections in the data.memberships parameter, but this can be a little fiddly and doesn’t work perfectly, so the second option (the one we will use) is the quickest way by setting up a second POST query to add the task to a different section.
Now, set this query to automatically trigger on success of the first ‘newTask’ in the query event handlers:
When you run the newTask query, it will create a new task in the specified project, and then trigger the next query to move this to the correct section.
Now, to connect the data of the errorLog temp state, we are going to add some details into the description of the task, using the data.html_notes parameter. You can either use data.notes or the data.html_notes version: in this case we are opting for html so that we can set the errorLog code to be in a code block for clarity.
Note: \n designates a new line and <code> … </code> defines a code block. We included a ternary for the user info if it’s left blank to send ‘None provided’, but this isn’t necessary if you make this field obligatory.
This html note will include the value of the text box summary we already programmed in our modal (errorTextSummary.value), the user information provided in the text input (textInput3.value), as well as the full error object from the errorLog temp state in a code block, where we used the JSON.stringify() function to parse the object into a string. This means that the developer has as much information as possible to fix the bug.
This is how that task description will look in Asana:
To make things as clear as possible, we also added an ‘assignee’ to the newTask parameters, so that the developer is notified:
Finally, connect the Submit button of the modal’s form to an event handler that triggers the newTask query. Make sure that the submission button is throttled for around 5 seconds (5000ms) after submit in the click event handler, so that it can only be submitted once while the queries run:
With that, you have a simple bug report being filed quickly to your Asana project as a ticket! Keep following to find out how to connect this to custom fields and set some priority tags.
For our final trick, we are going to set the values of some custom fields which are useful in a bug report, in this case ‘Priority’ and ‘Browser’. This part is a little fiddlier, and it’s worth noting that custom fields can only be created on premium versions of Asana. In this case, we used a Bug Report template, where these custom fields were pre-made, but you can learn more about creating them in the Asana documentation.
To connect to the custom fields of a workspace, you first need the gids. The best way to do this is a GET query to pull them in:
This will return all the custom fields available in your workspace. If the custom fields are specific to your project, you can use this query instead, and specify the project gid:
Now, head back to your Bug Report modal and add two Select components, one for the Priority and one for the Browser type:
In the component settings, connect the values of each to the array of custom field gids, and the label to the array of custom field names, so users are shown the human readable name but the associated value is the gid. like this:
Note: you will need to adjust the index number in the array to connect to the correct custom fields. You can use the preview option when drilling through the data to check the name of each custom field section. As these index numbers can change if different developers are logged into the same app, you may be better off hard coding these options as an array.
Now that your Select options are set, you can go back to the newTask query and connect them to Asana.
Under the data.custom_fields parameter, enter the references to the selected gids as a JSON object, by defining the key as the custom field gid, and the value as the select component value (the gid of the selected enum option). Separate each key:value pair with a comma:
Again, you can simply paste in your gid’s in place of the query reference.
Now your custom fields are connected!
Now let’s test this to see the results!
Woohoo! Now that’s all done, let’s clean up the UI a little by adding a clear success message to newTask after submitting the report:
Make sure the success notification is only enabled for one of your queries if you are addingTasktoSection as well, so that the user isn’t bombarded with messages. You should also set the modal to close on success of the newTask query, and the temp state to be set to false to clear.
Finally, and most importantly, make sure to connect each of your queries and action triggers (buttons etc) to the bug reporter by copying the event handler script from our first query.
Joey and his team helped Vial build our internal tools. Bold Tech was great to work with and were consistently thoughtful, communicative and had a high quality bar for their work.
Bold Tech were the right fit for TVadSync to accelerate our use of Retool platform. We had both user experience design needs as well as back end data design needs that were quickly resolved by the team. We will be using them for all Retool app development moving forward. Highly recommended.
