Showing results for 
Search instead for 
Did you mean: 

Engine Works Blog

Under the hood of Alteryx: tips, tricks and how-tos.

Have you ever received a vague error message and spent way more time figuring it out than you’d like to admit? Well, you’re not alone! Error messages can greatly improve the end-user experience (even if that end-user is only you), but it is often an afterthought in the development process. It’s immediate feedback that can help the user better understand how to configure your tool. This can range from notifying the user when a required field is empty to returning the HTTP response status code when connecting to an API. I will describe two ways you can provide error messages within your HTML macro: Alteryx message tools in the macro back-end and JavaScript manipulation of the DOM on the front-end. The examples used are from version 2 of the Publish to Tableau Server tool that was released with 2018.2.

Macro Back-end
In the macro back-end, the Error Message tool is best used to check for empty fields or specifically formatted fields that would halt processing in Alteryx. If you are making API calls, the Error Message tool is also useful for returning HTTP response codes in calls that are made during runtime. Configuring the Error Message tool is simple. You will likely have Interface widgets that must be populated or fields that require a specific format. Even though this information can be included in the help documentation, providing a real-time message to the user saves them time and confusion before running an incorrectly configured tool and receiving an indecipherable error message. Within the macro back-end, connect an Error Message tool to the Interface widget and give it a condition to check. If the condition returns true, you can enter your custom error message that will be displayed before the tool is run.

In this example, if a user attempts to leave the data source name empty, the message ‘Enter new or select existing data source name.’ will appear below the tool and within the Results pane.


Error_message_tool.pngThe Error Message tool 

Error_message_config.pngThe tool's configuration

Publish_to_tableau_server_tool.pngThe displayed error message

The other instance where messages are used within the macro back-end is the response from an API call made after the tool is run to publish the data to the Tableau Server. This error makes use of the Message tool, which checks to see if the string ‘error code=’ exists within the DownloadData field returned from an API call and, upon finding it, parses the field to form an error.




Together, the error from the missing data source name and the one returned from the API call give the user a clearer idea of where they went wrong.




‘Error Code 400000: Bad Request – Payload is either malformed XML/JSON or incomplete’ is a useful message, but knowing that you accidentally didn’t specify a data source name makes troubleshooting this error much easier.

Setting errors with JavaScript
If you are making multiple API calls that occur before the tool is run, like authentication, for example, that is where setting innerHTML to provide early messages to the user comes in handy. This doesn’t just apply to errors; we use it to notify the user when their connection information is saved or deleted in the latest version of the Publish to Tableau Server Tool.

Begin by setting up empty divs that will be utilized in the event of an error in the HTML file. Give the divs a unique id that will be used to specify which div will display which message later on in the Javascript. Think of these divs as placeholders that may or may not be filled; it depends on an error occurring. You can also style these elements by their id in the CSS. You’ll notice we use varying colors to indicate the severity of the message: red for errors, orange for warnings, and green for informative messages.


        <div id='aliasSaveMessage'></div>
        <div id='aliasDeleteMessage'></div>
      <br />
      <br />
      <div id='error'></div>


If an error is returned during authentication, which requires clicking the ‘Connect’ button on the interface, not the run button, it will appear at the bottom of the cluster of interface widgets. Let’s start out with a static error message. We need an error to show up if authentication fails and that API call is contained within the function set as the onClick event for the ‘Connect’ button. The following code snippet is from the authentication function.


  return await, data, config)


If an error is returned, it will be processed through errorMessaging, which has a little more going on than the snippet you’re about to see, but this is how you set the innerHTML of a div with id=’error’ to a static message.


document.getElementById('error').innerHTML = 'Danger, Will Robinson!'


And that will look like this in the interface:




Here is the empty div in the HTML before the error message:




And here it is after:




Sometimes static messages will suffice, but in most cases, your error messages will need to be dynamic. By parsing the error response from an API call, the following error message was pieced together.




It looks like this in the code:


    const status = (error.response.status === undefined) ? '' : `Status ${error.response.status}`
    const statusText = (error.response.statusText === undefined) ? '' : `: ${error.response.statusText}`
    const summary = ( === undefined) ? '' : `<br>${}`
    const errorCode = ( === undefined) ? '' : ` ${}`
    const detail = ( === undefined) ? '' : `: ${}`
    document.getElementById('error').innerHTML = status + statusText + summary + errorCode + detail


Errors might not be the only time you wish to communicate with your user. If the tool is doing something that is not immediately apparent to the user, it’s a good idea to include some messaging around it. The Publish to Tableau Server tool allows you to save connection information, which you can see if you refresh the dropdown, but it’s a better user experience if a message is displayed. The innerHTML of the div with id ‘aliasSaveMessage’ is set to the text ‘Connection Saved’ when the function that saves the connection info is called.




Same with deleting a connection –




It is also important to reset the messages when certain events occur, such as clicking the Connect button. If a user is satisfied with the connection they saved and attempt to click ‘Connect’, they no longer need to see the extra messages. At moments like that in your code, you can set it to blank with the following –


  document.getElementById('aliasSaveMessage').innerHTML = ''
  document.getElementById('aliasDeleteMessage').innerHTML = ''


These are only a few examples of where error messages are appropriate. Messages, in general, are key in optimizing the user experience. It makes troubleshooting easier and gives users the power to solve their own problems. Even if you are creating tools only for yourself, it’s still a good idea to get in the practice of including error messages. As you work on your tool, think of the possible pitfalls and provide users with meaningful messages that don’t require an insane amount of googling. Your users will be grateful, and you’ll also be improving your skills as a developer.

Blythe Early

Blythe is an Associate Product Manager that started her career at Alteryx as a Customer Support Engineer in January of 2015. She previously worked as a data analyst for a marketing company. She likes cats and video games and dislikes writing about herself in the third person.

Blythe is an Associate Product Manager that started her career at Alteryx as a Customer Support Engineer in January of 2015. She previously worked as a data analyst for a marketing company. She likes cats and video games and dislikes writing about herself in the third person.