An Introduction to Error Handling in Unqork

Overview

Error handling is the process of anticipating application errors an end-user might encounter. You can create pop-up messages that help end-users handle the errors during runtime. You can customize error messages and guide end-users so they don’t get lost or confused. Think of error handling like setting up bumpers in bowling. In this article, you'll also learn how to handle network errors. A network error is when a Plug-In or application programming interface (API) call fails. With error handling, you can display network errors to the end-user in a helpful way.

What You'll Learn

In this article, you'll learn how to:

Tell the difference between error handling and troubleshooting.
Define and recognize a network error.
Find network error details using the DevTools Console tab.
Word error messages for external and internal APIs.
Customize system-generated messages based on client preferences.

How is Error Handling Different from Troubleshooting?

Troubleshooting is the art of finding and fixing unexpected behavior in an application. In troubleshooting, you investigate the unexpected behavior. Then, you isolate where the error lives, work your magic, and get rid of the error. Error handling is the process of anticipating errors that your end-user can face. Then, you create pop-up messages that help end-users handle the error.

In summary: troubleshooting deals with configuration errors. Error handling predicts potential runtime errors and helps end-users through the use of pop-up messages.

For the most part, you'll do error handling on Plug-Ins and API calls. You can also refer to these errors as HTTP errors, or network errors.

What is a Network Error?

A network error is when a Plug-In’s API call fails. The Plug-In component comes with an Error Trigger field in the component’s settings. The Error Trigger is where you set up a failsafe for your Plug-In. If there’s an error, the Plug-In triggers what you defined as the Error Trigger. It's best practice to set up error handling every time you make API calls. Error Handling network errors is a way of being kind to future you. Being proactive now prevents issues down the road.

API calls can fail with third-party APIs or Unqork’s internal APIs. Unqork has an object called integratorErrors that houses errors for all Plug-Ins. When setting up error handling, extract information from integratorErrors. Unqork then concatenates the error information into a pop-up message for your end-user. Concatenate is a function that joins 2 or more text strings into one string. You'll learn how you can access integratorErrors’ error information in the next section.

There are various ways an API call can fail. Error handling prepares you for any type of failed API call. The error handling process boils down to two steps:

Leverage the error code and message from the integratorErrors object.
Create custom pop-up error messages based on the client’s requirements.

Finding Network Error Details Using the Console Tab

The DevTools Console tab shows the details of API calls. The Console tab houses integratorErrors, which shows details of the failed API calls. This information is what you concatenate into pop-up messages for your end-user. The Console tab can be confusing for an end-user, which is why you use error handling.

To open the DevTools Console tab:

Preview your module in Express View. This module is where you encountered a network error (failed API call).

Right-click anywhere on your Express View page.

Select Inspect. The DevTools panel opens on the right side of your screen.

TIP If you use a Mac, holding Command + Option + i also opens DevTools.

Click the Console tab at the top of the DevTools panel.

At the bottom of the Console’s feed, there’s a blue arrow to the left of a blank row. The blue arrow indicates the Console’s command line. This command line is where you enter commands to get more submission details.

Next, use the angular command to get to the integratorErrors object.

To find the error code and error message from integratorErrors, continue as follows:

Enter angular.element(".unqorkio-form").scope().submission next to the blue arrow in the Console’s command line.

Press Enter/Return on your keyboard.

Click the solid drop-down arrow to the left of the response in your Console panel. The response should start with, “{data: {...}”.

Click the solid drop-down arrow to the left of integratorErrors.

Click the solid drop-down arrow to the left of the Console line with your Plug-In’s name.

You’ll see the error code and error message for your Plug-In. This information shows why the Plug-In failed.

In our Error Handling Use Case article, you can learn how to configure a pop-up message like the one above. You'll learn how to extract the error code and message from the integratorErrors object. Then, you’ll learn how to concatenate the code and message into a pop-up error message. First, you'll learn about best practices for error handling.

Network Error Messages

Unqork uses two types of pop-up error messages:

Error Message	Description
System-Generated Error Response	Created by concatenating values and codes from the integratorErrors object. This object houses all Plug-In error codes and messages. An example of a system-generated error response is "404 - Module not found."
Customized Error Response	The more user-friendly option, customized error responses can be anything your client wants. Use these for directing the user on what they should do next. An example of a customized error response is "Error: Request to Salesforce failed. Please try again later."

Each company decides which style pop-up message they want for their network errors. Whatever displays in the error pop-up message should align with the client’s needs. Here are some tips on how to word error messages for external and internal APIs.

Error Messages for External APIs

Business teams have specific requirements for when their third-party API fails. Using these requirements, you can create error messages on the front-end.

Most vendors publish an error code list for third-party APIs. Or, you can ask for a copy. These lists help you see what kind of errors you can expect from each third-party API. Error code lists can help you better plan your error handling.

One of the external APIs Unqork uses is Salesforce. Salesforce publishes a list of all error codes and messages that can happen with their API. If you have an integration with Salesforce and an API call fails, you’ll receive one of these codes.

You can find Salesforce error codes here: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/errorcodes.htm.

Error Messages for Internal APIs

Start by working with the client and decide which type of messages they want for their application. With an internal API, try using response codes that mimic standard responses for Representational State Transfer (REST) APIs.

You can find REST APIs standard status codes here: https://restfulapi.net/http-status-codes/.

NOTE You'll learn how to error handle within remote executes and the proxy model in the Error Handling Advanced Use Case.

Creating a Pop-Up Error Message

You’ll set up your pop-up error messages using a combination of components. For the back-end, you’ll need a series of logic components that retrieve data. These logic components work together and display pop-up error messages on the front-end. The pop-up messages help your end-user handle any error they might encounter.

In the next lessons, you'll learn how to configure pop-up error messages.