Tracking & Reporting Bugs in Retool Using Asana

Sophie Becker
March 28, 2022

Call me an entomophobe, but don’t we all hate a bug? And one pesky side-effect of Retool app bugs is the confusion that occurs when a query error message starts popping up around the top of your screen. Unfortunately, depending on the resource, these error messages give failure responses aimed at developers, and not at the technically-spooked, making it difficult for users to report exactly what went wrong.

That’s why in this tutorial we will show you how to make a bug reporting modal for your internal tools, 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 to your Bug Reporting Tool (such as Asana, or Zendesk), 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. 

GIF showing final bug reporting app in Retool and Asana

Setting up your Bug Report

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). 

error log temp state

Next, we'll perform a single script inside of an event handler to initialize our errorLog and open our error Modal on failure

error log modal open event handler in retool

errorLog.setValue(self);errorModal.open()

As you can see here, on failure of this query the modal will open and the temporary state will be set to (self), in this case 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:

retool temp state populated with error log

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. Insert a modal into your app and set its Hidden status to 'true', so that the modal is only triggered to open by a query failure.

Inside your modal, pull in a text box for the title of the Bug Report, and then add a Form component with another text box for the error information. To include this data, your text component value will look a little like this:

text component linked to error

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, as generated by the query. 

App: {{retoolContext.appName}} app ‍
User: {{current_user.email}}‍
Errored Query: {{errorLog.value.id}}‍
Error Type: {{errorLog.value.data.error == true ? ‘N/A’ : errorLog.value.data.error}}‍
Message: {{errorLog.value.data.message}}‍
Code: {{!errorLog.value.data.statusCode ? 'N/A' : errorLog.value.data.statusCode }}

Below your error information, 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:

Bug report modal populated with error response

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.

Now, we need to set up the 'Submit' button to send this information to your ticketing system.

Connecting your Retool Bug Modal to your Bug Report Board in Asana

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.

Connecting to Asana

If you don’t have Asana connected already, create a new query and head to ‘Create a new resource’:

Resource list in Retool

Select Asana from the list,

List of resources Retool

And then all you need to do is give it a name, test your OAuth connection and click Create Resource to log in through Asana.

Asana connection Retool

Once you are logged in, you’ll have access to a list of preset API calls through the ‘operation’ drop-down in your query:

List of integrated queries for Asana

Collecting your Asana Workplace, Project and Section GIDs

To set up this post query, 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 task list). 

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 workspace query asana in retool

GET/projects, which will return the project names and gids:

get projects asana query in retool

And finally GET sections, where you will take the project gid from the previous getProjects query to pull in the sections available on that project (note: this information is harder to find in Asana's platform):

get sections asana query in retool

Once you've pulled in these gids, it’s best to copy and paste them for the next queries, rather than referencing the query response, as the reference index number of each project can change depending on the developer using the app. 

Now that you have all the relevant gids, you can create a POST /tasks query. This will connect to your bug form and send the relevant information to the task board once submitted.

This is how ours looked:

new task query for asana in retool

In the data.workspace parameter and in the data.projects parameter, we have inserted the workspace and project gid. Note the project in box brackets as this input requires an array (ARR).

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 run this query, it should post an Asana task like this:

Asana ticket with Retool bug

Include the Error Log data in the Asana task description

Now we have our task set up and posting to Asana, we need to include all the data from our error log temp state.

To do this, 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: we are opting for html so that we can use <code> to set the errorLog code to be in a code block for clarity. 

data.html code for the task description in asana


'<body<{{errorTextSummary.value}}
\nUser Info: {{!textInput3.value ? 'None Provided' : textInput3.value}} 
\nFull error:
<code<{{JSON.stringify(errorLog.value)}}</code<</body<'

📌 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’.

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:

description of error in asana task

To make things as clear as possible, we also added an ‘assignee’ to the newTask parameters, so that the developer is notified:

task assignee in retool query

Now that our 'newTask' query is fully populated, we need to connect the form Submit button to an event handler that triggers the query. It's a good idea to 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:

Click handler for the form 'Submit' button

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, set some priority tags and move the task to another section. 

Connecting bug report to Asana custom fields

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 for our Asana board, 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'll need those gids again. Like we did before, the best way to do this is a GET query to pull them in: 

get custom fields query in retool

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:

get custom field settings asana

Now, head back to your Bug Report modal and add two Select components, one for the Priority and one for the Browser type:

bug report with added dropdowns in retool

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:

mapped fields for a select dropdown
The 'Priority' dropdown option labels are populated by the custom field names, and the values by their respective gids.

mapped fields for a select dropdown
As above, but for the browser options.

📌 Note: you will need to adjust the index number in the array - ['1'] in the code above - to connect to the correct custom fields. As these index numbers can change if different developers are logged into the same app it may be better to hard code these options as an array.

Now that your dropdown 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: 

JSON object defining custom fields in asana


{'{{getCustomFields.data.data['0'].gid}}':'{{prioritySelect.value}}','{{getCustomFields.data.data['1'].gid}}':'{{browserSelect.value}}' }

Again, you can simply paste in your gid’s in place of the query reference.

Now your custom fields are connected!

Adding the task to the correct section in Asana

So far, when we set up a new task, it's automatically posted to the first (or left-hand) section, or column, of the Asana project. If you need to, there are two ways to define a different section for this task.

In the Asana docs, there is an option to define the target section in the data.memberships parameter, but in our experience this can be a little fiddly and doesn’t work perfectly, so the option we will use is by setting up a second POST query to move the task to a different section.

This query uses the section gid (which we copied from the getSections query response), and references the response of the newTask query we just created, referencing the gid using {{newTask.data.data.gid}}.

move section asana query

Now, go back to the original 'newTask' query and set it to trigger the 'addTasktoSection' query on success in the event handlers.

success handler for query

Now, when you run the newTask query, it will create a new task in the Asana project, and then, on success, trigger the next query to move this task to the correct section. 

Results and Final Touches

Now let’s test this to see the results!

gif of a bug report in retool sending the error response to asana

Now that’s all done, let’s clean up the UI a little by adding a clear success notification 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.

In this same event handler section, you can also set the modal to close on success of the newTask query, and the temp state to be set to false to clear the form.

Finally, and most importantly, make sure to connect each of the queries and action triggers (buttons, for instance) in your app to the bug reporter by copying the failure event handler script from our first query. 

Now you have a simple system to help report key Retool bugs to engineers with all the error log information!

Subscribe to get updates when we post
Thanks for subscribing!
Oops! Something went wrong while submitting the form.
TVadSync

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.

Justin Gage Testimonial - Founder of Technically and Growth at Retool
Ronan Higgins, CEO
Delivery Dudes

Bold Tech is the go to for all Retool work. Save your engineering team the hassle and partner with them, you wont regret it.

Justin Gage Testimonial - Founder of Technically and Growth at Retool
Parker Rex, Product Manager