Handling in Unqork

Error handling is the process of anticipating errors an end-user might encounter and creating pop-up messages to guide them through resolving those errors at runtime.

This article also covers how to handle network errors. A network error occurs when a Plug-In component or API call fails. With error handling, display network errors to end-users in a way that helps them respond appropriately.

How Is Error Handling Different from Troubleshooting?

Troubleshooting is the process of finding and fixing unexpected behavior in an application: investigate the behavior, isolate its source, and eliminate it.

Error handling is different. It is the process of anticipating errors that end-users might face and creating pop-up messages that help them respond on their own. Error handling primarily applies to Plug-In components and API calls, also called HTTP errors or network errors.

What Is a Network Error?

A network error is when a Plug-In component's API call fails. The Plug-In component has an Error field in its settings that defines a fallback component for when a call fails. If there is an error, the Plug-In triggers that component. As a best practice, set up error handling every time an API call is made.

API calls can fail with third-party APIs or Unqork's internal APIs. Unqork has an object called integratorErrors that stores errors for all Plug-In components. When setting up error handling, extract information from integratorErrors. Unqork then joins the error information into a pop-up message for end-users.

The error handling process involves two steps:

• Use the error code and message from the integratorErrors object.

• Create custom pop-up error messages based on what end-users need.

Finding Network Error Details Using the Console Tab

Use the DevTools Console tab to access integratorErrors and see details of failed API calls. Use this information to build pop-up messages for end-users.

To open the DevTools Console tab:

1. Click UI View to open Express View in the Module Builder, specifically the module where the network error occurred.

2. Right-click anywhere on the Express View page.

3. Click Inspect. The DevTools panel opens on the right side of the screen. On a Mac, press Command + Option + I to open DevTools directly.

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

A blue arrow at the bottom of the Console's feed indicates the command line. Use this field to query the submission data directly.

To find the error code and error message from integratorErrors:

1. At the Console command line, enter angular.element(".unqorkio-form").scope().submission.

2. Press Enter or Return.

3. Click the expand arrow to the left of the response in the Console panel. The submission object expands to display its top-level properties, including integratorErrors.

4. Click the expand arrow to the left of integratorErrors.

5. Click the expand arrow next to the Plug-In component's name.

The error code and error message for the Plug-In component display here. This information indicates why the Plug-In component failed.

Network Error Messages

Unqork uses two types of pop-up error messages:

The style of pop-up message depends on the application's requirements and the needs of its end-users. Whatever displays in the error pop-up should align with end-users' needs. The following sections cover 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. Use these requirements to create error messages on the front end.

Most vendors publish an error code list for third-party APIs, or one can be requested from the vendor. These lists help identify what kinds of errors to expect from each third-party API and help plan error handling.

Error Messages for Internal APIs

Work with the team to decide which type of messages to use for the application. With an internal API, use standard REST response codes.

See REST API HTTP status codes for the standard reference.

Creating a Pop-Up Error Message

Pop-up error messages use a combination of components to retrieve error details from integratorErrors and display them to end-users at runtime.

To build a pop-up error message for your application, describe the goal to the Build Agent in the Module Builder. The agent can walk through the component configuration interactively based on your specific setup.

See Also

• Common Troubleshooting Strategies — common strategies for diagnosing issues in Unqork applications.
• Troubleshooting Unqork Applications — the investigate, isolate, and terminate approach.
• Plug-In Component — making API calls in Unqork modules.