How to: Configure a Pop-Up Error Message

Overview

There are various ways to go about error handling. As you practice configuring in Unqork, you'll find the component setups that work best for you. Below, you can see one of the common ways Unqork developers configure pop-up error messages. You can use the same error message configuration for external and internal API errors.

Here are the basic steps of an Unqork pop-up error message:

1.

A network request fails.

2.

Unqork retrieves the error code and message from the integratorErrors object.

3.

Unqork displays the error code and message to the end-user by way of a pop-up message. You can customize the message and direct the end-user on how to handle the error.

The integratorErrors object only populates if you enter a Property ID or dummy value into the Error Trigger field.

Start by setting up a system-generated error message. Your end-user sees this message when there's a network error in your application. Here's how your error message looks in Express View:

Here's how your completed module looks in the Module Builder.

What You'll Need

One note before you start; when error handling real-life network errors, work with an existing Plug-In. For this use case configuration, add a Plug-In and a Button component. The Plug-In allows you to manufacture an error. The Button allow you to prompt the pop-up error message. When error handling in a real-life scenario, you can skip the Button and work with an existing Plug-In.

To create a Plug-In error so you can practice error handling, you'll need:

• 1 Panel component
• 1 Plug-In component
• 1 Button component

To configure a pop-up error message, you'll need:

• 1 Panel component
• 1 Calculator component
• 2 Hidden components
• 1 Decision component

Configuration Part 1: Create a Broken API Call

First, create a broken API call so you can prompt your pop-up error message. When error handling an existing Plug-In, skip to Configuration Part 2: Create a Pop-up Error Message.

Configure the Panel Component

This Panel acts as a container for the components that follow.

1.

In the Module Builder, drag and drop a Panel component onto your canvas.

2.

Enter panelCreateError in the Property Name field. You can leave the Title blank.

3.

Click Save.

Configure the Plug-In Component

For this use case, you need a Plug-In. The goal in this use case is to create an error. So, your Plug-In must reference a module ID that doesn't exist.

1.

Drag and drop a Plug-In component onto your canvas. Place your Plug-In inside the panelCreateError Panel.

2.

Enter pluginName in the Property ID and Label Text fields.

3.

Set the Trigger Type to Manual.

4.

Select Execute Module from the Internal Services drop-down. /fbu/uapi/modules/{moduleId}/execute displays in the Data Source URL field.

5.

Replace "{moduleId}" with 5ece9eee597dbe01f8ef308cs.

6.

Click Save.

Configure the Button Component

Clicking the Button triggers the pluginName Plug-In, which prompts the error that you configured.

1.

Drag and drop a Button component onto the canvas. Place your Button under the pluginName component.

2.

Enter btnTest in the Property ID field.

3.

Enter Test Error in the Label Text field.

4.

Set the Button Action Type to Event.

5.

Enter pluginName in the Trigger on Click field.

6.

Click Save.

Configuration Part 2: Create a Pop-Up Error Message

Now, practice how to configure pop-up error messages. Remember, you can create a system-generated message with a standard code and message. Or, you can customize a more user-friendly message. The steps for each approach are the same.

To set up an error message for your end-user:

Configure the Panel Component

This Panel acts as a container for the components that follow.

1.

In the Module Builder, drag and drop a Panel component onto your canvas. Place your Panel below the panelCreateError Panel.

2.

Enter panelErrorHandling in the Property Name field. You can leave the Title blank.

3.

Click Save.

Configure the Calculator Component

Next, bring in a Calculator component. The Calculator extracts and concatenates (joins) the error message and code from integratorErrors.

1.

Drag and drop a Calculator component onto the canvas. Place your Calculator in the panelErrorHandling Panel.

2.

Enter calcErrorHandling in the Property ID and Label Text fields.

3.

Set the Trigger Type to Manual.

4.

In the Inputs table, enter the following:

a.

Property ID: enter integratorErrors.

b.

Alias: enter A.

c.

Required: Yes (selected).

5.

In the Outputs table, enter the following:

6.

Click Save.

Configure the Hidden Components

Use 2 Hidden components in this configuration. The first component houses the error code, and the second houses the error message.

1.

Drag and drop 2 Hidden components onto your canvas. Place your Hidden components below the Calculator.

2.

Enter the following Property IDs and Label Text:

3.

Click Save after adding each component.

Configure the Decisions Component

This Decisions component creates the pop-up error message for your end-user.

1.

Drag and drop a Decisions component onto the canvas. Place it below the Hidden components.

2.

Enter ruleIntegratorErrors in the Property ID and Label Text fields.

3.

In the Inputs table, enter the following:

4.

In the Outputs table, enter the following:

a.

Property ID: enter panelErrorHandling.

b.

Type: enter popError.

5.

In the Micro Decisions table, enter the following:

a.

panelErrorHandling_popError: enter =CONCATENATE(errorCode,' ',errorMessage).

6.

Click Save.

You can learn more about the CONCATENATE function here: https://support.office.com/en-us/article/concatenate-function-8f8ae884-2ca8-4f7a-b093-75d702bea31d.

Update the Plug-In Component's Error Trigger

Finally, set calcErrorHandling as the Error Trigger of your Plug-In. This setup means that any time there's an error in your Plug-In, calcErrorHandling fires.

To update your Plug-In's Error Trigger:

1.

Hover over the pluginName Plug-In component.

A 5-button toolbar displays above the component on hover-over.

2.

Using the toolbar, click the (Settings) button.

3.

Enter calcErrorHandling in the Error Trigger field.

4.

Click Save.

5.

Save your module.

Test Your Pop-Up Error Message

Now it's time to see your work in action. To test your pop-up error message:

1.

Click the Preview Module button in the top right of the Module Builder. Your module shows in Express View.

2.

Click the Test Error button. You'll see a pop-up error message with the message you configured.

Summary

Great job! Let's recap. When there's an error in your Plug-In's call, the following now occurs:

1.

The Plug-In triggers its Error Trigger, calcErrorHandling.

2.

The calcErrorHandling extracts network error information from the object integratorErrors.

3.

The calcErrorHandling outputs the error code and message to your 2 Hidden components.

4.

The ruleIntegratorErrors concatenates the error code and error message from the Hidden components.

5.

The ruleIntegratorErrors displays a pop-up message to the end-user.

Remember, there are many ways you can configure pop-up error messages. As you get more comfortable with Unqork, you'll learn your favorite component setups.

Lab

You can find the completed use case for your pop-up error message configuration here: https://training.unqork.io/#/form/5ed1602860c43a020e6dc48b/edit.