How to: Configure Multiple Error Messages

Overview

Now that you know how to configure a basic pop-up error message, you can move to an advanced use case. When configuring in Unqork, you'll often use remote executes. A remote execute is when a module executes behind-the-scenes or at the server-side. Some configurations require layers of many remote executes or multiple Plug-In calls. It's best practice to error handle every Plug-In that you have in your configuration. If there's an error in a Plug-In call, your end-user must see a pop-up message.

In this article, you'll learn how to error handle remote execute calls that trigger other calls. Once you learn how this configuration works, you can apply it to any number of calls.

Use Case

In this use case, a front-end module remote executes a back-end module. The back-end module then fires an internal application programming interface (API) call.

Let's look at the 2 modules in this advanced error handling use case:

Module

Description

Front-End Remote Execute Module

This is the module that the end-user interacts with in Express View. The end-user clicks a Button that fires a Plug-In component. The Plug-In remote executes to the Back-End API Call Module.

This module is the only one the end-user sees. So, configure pop-up error messages for both modules' Plug-Ins here.

NOTE  Refer to this module as the front-end module.

Back-End API Call Module

This module makes the API call. For this use case, use the Get Submissions API call.

This API call retrieves submission data to display on a dashboard to the end-user. In this use case, your focus is on handling errors rather than viewing submissions. So, skip the dashboard.

NOTE  Refer to this module as the back-end module.

Since there are 2 calls (1 remote execute and 1 internal API call), there are 2 chances for errors. You'll set up error handling for both calls. The goal is to error handle all Plug-Ins and configure error messages on the front-end module. From there, any error down the line fires pop-up messages for the end-user in Express View. The end-user stays informed no matter where the error happens.

Here's how your error message looks in Express View if a remote execute call fails:

Here's how your error message looks in Express View if the Get Submissions API call fails:

In real-life configuration, you can choose to have a generic message. End-users might not know what a remote execute or API is, so use a message that's easier to understand. For this use case, each call has a unique error message. Use this approach so you can test the error handling of both calls.

What You'll Need

Set up your pop-up error messages using 2 modules and a combination of components. The components work together and display pop-up error messages on the front-end. If you have more modules, you can adjust your configuration as needed. To recreate your entire use case lab, move through the Pre-Configuration section first. If you already have a remote execute setup, skip to the Error Handling Configuration section.

You can configure the error handling for these modules in any order. In this case, start with the API call.

Back-End API Call Module

Begin by creating the Back-End API Call Module. In this module, set up a Plug-In to get submission data.

To set up the Get Submissions API, you'll need:

  • 1 API Specification template

  • 1 Initializer component

  • 1 Plug-In component

  • 2 Hidden components

For error handling the API call, you'll need:

  • 1 Initializer component

  • 1 Hidden component

If the API call fails, the back-end module tells the front-end module about the failure. The front-end module then fires a pop-up message for the end-user in Express View. And so, you have a bit of configuration to do on the front-end module to map the back-end error to the front-end.

Here's how your completed Back-End API Call Module looks in the Module Builder:

Front-End Remote Execute Module

Next, build the Front-End Remote Execute Module. In this module, set up a Button that remote executes the Back-End API Call Module. The front-facing module is also where you configure your pop-up error messages. No matter where the error happens down the line, the end-user sees a pop-up on the front-end in Express View.

To set up the front-end configuration, you'll need:

  • 1 Panel component

  • 1 Plug-In component

  • 1 Button component

To error handle the front-end module's remote execute, you'll need:

  • 1 Panel component

  • 1 Initializer component

  • 1 Hidden component

  • 1 Decision component

Set up a pop-up message on the front-end for the Back-End API Call Module as well. If you have additional Plug-Ins, also configure pop-up messages for each of those on the front-end. Every Plug-In should have an Error Trigger and error handling.

To set up an error message on the front-end for the back-end's API call, you'll need:

  • 1 Panel component

  • 1 Hidden component

  • 1 Decision component

NOTE  Say you have other modules and Plug-Ins and you want each to have a pop-up error message on the front-end. Use these same 3 components on the front-end for each pop-up error message you want to configure.

Here's how your completed Front-End Remote Execute Module looks in the Module Builder:

Pre-Configuration

First, build out the remote execute setup and the API call. If error handling an existing setup, skip to the Error Handling Configuration section.

Back-End API Call Module

This back-end module makes the API call. For this use case, use the Get Submissions API call. The front-end module remote executes this back-end module, which fires the API call. This process all happens behind the scenes.

Configure the API Specification Template

The API Specification template contains text and 3 Panels to help with an API setup. These 3 Panels and text live in a template Panel called panelAPITemplate. Think of the panelAPITemplate Panel as the transportation for the API layout. Once you add the template, move the 3 Panels out of panelAPITemplate. Then, remove panelAPITemplate.

To add the API Specification Template to your module:

1. In the left sidebar of the Module Builder, click Templates.
2. Enter API Specification in the search bar.
3. Drag and drop the API Specification template onto your canvas.

You must move the 3 Panels out of the panelAPITemplate Panel in order for the API call to work. Then, you can remove the empty panelAPITemplate.

1. Drag and drop panelInfo, panelRequest, and panelResponse below the panelAPITemplate.
2. Hover over the panelAPITemplate.

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

3. Using the toolbar, click the (Remove) button.
4. Save your module.

NOTE  The API Specification template comes standard with some HTML text. This text is to guide you when building out your API structure. You can keep or delete the text.

Configure the Initializer Component

This Initializer component triggers the Plug-In component that you set up next.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the panelInfo Panel.
2. Enter initPluginGetSubmissions in the Property ID and Label Text fields.
3. Select New Submission from the Trigger Type.
4. In the Outputs table, enter the following:
a. Property ID: enter pluginGetSubmissions.
b. Type: enter trigger.
c. Value: enter GO.

5. Click Save.

Configure the Plug-In Component

For this use case, you need a Plug-In component. The Plug-In fires the Get Submissions API.

1. Drag and drop a Plug-In component onto your canvas. Place your Plug-In inside the panelInfo Panel, under initPluginGetSubmissions.
2. Enter pluginGetSubmissions in the Property ID and Label Text fields.
3. Select Manual from the Trigger Type.
4. In the Inputs table, enter the following:

Property ID

Mapping

moduleId

moduleId

fields

fields

5. Select List Submissions for Dashboard from the Internal Services drop-down. /fbu/uapi/system/getSubmissions displays in the Data Source URL field.

6. Click Save.

Configure the First Hidden Component

Use 2 Hidden components in this configuration. The first component houses the fields of the submission data. The second component houses the module ID of the Front-End Remote Execute Module.

NOTE  Since this use case is about error handling, you don't have actual submission data. These Hidden components are placeholders for the purpose of this use case.

To configure the first Hidden component:

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelRequest Panel.
2. Enter fields in the Property ID and Label Text fields.
3. Click Save.

Configure the Second Hidden Component

Your second Hidden component, moduleId, houses the module ID of the front-end module.

To configure the second Hidden component:

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelRequest Panel.
2. Enter moduleId in the Property ID and Label Text fields.
3. Enter 5f0f5dc4a7aaa20205d8a48e in the Default Value field.

NOTE  This is the module ID of our Front-End Remote Execute Module. You can find this ID from your front-end module's hyperlink as follows: https://training.unqork.io/#/form/5f0f5dc4a7aaa20205d8a48e/edit

If you created your own front-end module, enter your module's unique module ID.

4. Click Save.
5. Save your module.

Front-End Remote Execute Module

Now, set up the front-facing configuration where your end-user interacts with your module.

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 panelRemoteExecute in the Property Name field. You can leave the Title blank.
3. Click Save.

Configure the Plug-In Component

This Plug-In remote executes and sends the end-user's information to the back-end module.

1. Drag and drop a Plug-In component onto your canvas. Place your Plug-In inside the panelRemoteExecute Panel.
2. Enter pluginRemoteExecuteAPI in the Property ID and Label Text fields.
3. Select Manual from the Trigger Type.

4. Select ExecuteModule from the Internal Services drop-down. /fbu/uapi/modules/{moduleId}/execute displays in the Data Source URL field.
5. Replace "{moduleId}" with the back-end module's ID. In this case, we entered 5f0f5df7804251020c3b89e0.

6. Click Save.

Configure the Button Component

Clicking the Button triggers the pluginRemoteExecuteAPI Plug-In, which prompts the remote execute.

1. Drag and drop a Button component onto the canvas. Place your Button inside the panelRemoteExecute Panel. You can place the Button above or below the pluginRemoteExecute Plug-In.
2. Enter btnGetSubmissionsAPI in the Property ID field.
3. Enter Execute Get Submissions API in the Label Text field.
4. Select Event from the Button Action Typeoptions.
5. Enter pluginRemoteExecuteAPI in the Trigger on Click field.

6. Click Save.
7. Save your module.

Error Handling Configuration

Now you can practice configuring pop-up error messages for more than one call. Remember, you want the pop-up error messages on the front-end module. This setup ensures your end-user sees the error messages if a call fails. When error handling layers of calls, there's back-end and front-end configuration.

Error Handle the Back-End API Call Module

Add an Initializer as the Error Trigger for the back-end module's API call Plug-In. Then, add a Hidden field to hold the error response if the API call fails.

To set up error handling on the back-end module's API call:

Configure the Initializer Component

This Initializer is the Error Trigger for the pluginGetSubmissions Plug-In. If the Get Submissions API call fails, this Initializer outputs the error response into a Hidden component.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the panelInfo Panel, below the pluginGetSubmissions Plug-In.
2. Enter initError in the Property ID and Label Text fields.
3. Select Manual from the Trigger Typeoptions.
4. In the Outputs table, enter the following:
a. Property ID: enter apiResponseError.
b. Type: enter value.
c. Value: enter There was an error with the Get Submissions call.

Create a Hidden component in the next step that matches this Output ID.

5. Click Save.

Update the Plug-In Component's Error Trigger

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

To update your Plug-In's Error Trigger:

1. Hover over the pluginGetSubmissions Plug-In component.

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

2. Using the toolbar, click the (Settings) button.

Note: If you're error handling your own Plug-In, open your Plug-In.

3. Enter initError in the Error Trigger field.
4. Click Save.

Configure the Hidden Component

This Hidden component houses the error response for the API call. When the API call fails, the initError Initializer fires. The Initializer then outputs an error response into this Hidden component.

To configure the Hidden component:

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelResponse Panel.
2. Enter apiResponseError in the Property ID and Label Text fields.
3. Set the Store Data in Database toggle to ON.

Storing this Hidden component in the database means you can map to it later. You'll use mapping when you bring the API's error response to the front-end module.

4. Click Save.
5. Save your module.

Error Handle the Front-End Remote Execute Module

Next, set up error handling for the remote execute call in the front-end module.

Configure the Initializer Component

In the next step, set this Initializer as the Error Trigger for the pluginRemoteExecuteAPI Plug-In. If the remote execute call fails, the Initializer outputs the error response into a Hidden component.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the panelRemoteExecuteError Panel.
2. Enter initRemoteExecuteError in the Property ID and Label Text fields.
3. Select Manual from the Trigger Typeoptions.
4. In the Outputs table, enter the following:
a. Property ID: enter remoteExecuteError.
b. Type: enter value.
c. Value: enter error.

Then, create a Hidden component in the next step that matches this Output ID.

5. Click Save.

Update the Plug-In Component's Error Trigger

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

To update your Plug-In's Error Trigger:

1. Hover over the pluginRemoteExecuteAPI Plug-In component.

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

2. Using the toolbar, click the (Settings) button.

NOTE  If you're error handling your own Plug-In, open your Plug-In.

3. Enter initRemoteExecuteError in the Error Trigger field.
4. Click Save.

Configure the Hidden Component

This Hidden component houses the error response if the front-end's remote execute fails.

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelRemoteExecuteError Panel, below the initRemoteExecuteError Initializer.
2. Enter remoteExecuteError in the Property ID and Label Text fields.
3. Click Save.

Configure the Decisions Component

This component displays an error message to your end-user if your remote execute fails.

1. Drag and drop a Decisions component onto the canvas. Place your Decisions component inside the panelRemoteExecuteError Panel, below the Hidden component.
2. Enter ruleShowRemoteExecuteError in the Property ID and Label Text fields.
3. In the Inputs table, enter the following:
a. Property ID: enter remoteExecuteError.
b. Type: enter exact.
c. Required: Yes (checked).
4. In the Outputs table, enter the following:
a. Property ID: enter panelRemoteExecuteError.
b. Type: enter popError.
5. In the Micro Decisions table, enter Uh-oh, there was an error with your remote execute call. under panelRemoteExecuteError_popError.

6. Click Save.
7. Save your module.

Now, if your remote execute fails, the end-user sees the message you set in your Decisions component.

Adding a Pop-Up Error Message for the API Call

Next, create a pop-up error message for the back-end module's API call. Remember, you configure all pop-up error messages on the front-end module. That way, if any calls fail, your end-user sees an error message in Express View.

Update the Plug-In Component's Output Mapping

Then, update your pluginRemoteExecuteAPI Plug-In. This update maps the back-end module's apiResponseError Hidden field to a Hidden field you'll add on the front-end module.

To update the mapping of your front-end module's Plug-In:

1. Hover over the pluginRemoteExecuteAPI Plug-In component.

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

2. Using the toolbar, click the (Settings) button.

NOTE  If you're error handling your own Plug-In, open your Plug-In.

3. In the Outputs table, enter the following:
a. Property ID: enter responseAPIErrorFrontEnd.
Note: You'll create a Hidden component matching this ID in a couple of steps.
b. Mapping: enter data.resolved.apiResponseError.

NOTE  apiResponseError is the name of the Hidden component on the back-end module. Since you set apiResponseError to store in the database, you can now map to that field. You can find mapping values using the angular command in the DevTools Console.For help with the DevTools Console, head over to Troubleshooting Strategies.

4. Click Save.

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 the Panel below the panelRemoteExecuteError Panel.
2. Enter panelAPIError in the Property Name field. You can leave the Title blank.
3. Click Save.

Configure the Hidden Component

This Hidden component houses the error response if the back-end API call fails.

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelAPIError Panel.
2. Enter responseAPIErrorFrontEnd as the Property ID and Label Text fields.
3. Click Save.

Configure the Decisions Component

This component displays an error message to your front-end user if the back-end's API call fails.

1. Drag and drop a Decisions component onto the canvas. Place your Decisions component inside the panelAPIError Panel, below the Hidden component.
2. Enter ruleShowAPIError in the Property ID and Label Text fields.
3. In the Inputs table, enter the following:
a. Property ID: enter responseAPIErrorFrontEnd.
b. Type: enter exact.
c. Required: Yes (checked).
4. In the Outputs table, enter the following:
a. Property ID: enter panelAPIError.
b. Type: enter popError.
5. In the Micro Decisions table, enter Oh no! Your API call failed! under panelAPIError_popError.

6. Click Save.
7. Save your module.

Test Your Pop-Up Error Messages

Now it's time to see your work in action. You have 2 different Plug-In calls, and each has its own error handling. To test the error messages, you must break each call. When a call fails, the Error Trigger fires, which triggers a pop-up error message on the front-end.

An easy way to break a call is to add a bracket to the Plug-In's Data Source URL. If the URL is incorrect, the call fails, and you receive a pop-up error message. Once you verify that your error message works, you can remove the bracket from the Data Source URL.

Error Message for the Remote Execute Call

Now, test your error handling for the remote execute call on the front-end module. First, break the Plug-In, which forces an error. Then, check that the error message pops up in Express View.

To break the Plug-In:

1. Open the front-end module in the Module Builder.
2. Hover over the pluginRemoteExecuteAPI Plug-In component.

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

3. Using the toolbar, click the (Settings) button.

NOTE  If you're error handling your own Plug-In, open your Plug-In.

4. Enter a bracket somewhere in the Data Source URL.

5. Click Save.
6. Save your module.

To test that your pop-up error message works:

1. Open your front-end module in Express View.
2. Click the Execute Get Submissions API Button.

A pop-up displays with the error message that you set in the ruleShowRemoteExecuteError Decisions component.

Error Message for the API Call

You can now test your error handling for the Get Submissions API call. First, break the Plug-In, which forces an error. Then, check that the error message pops up in Express View. Remember, you want all error messages to pop up on the front-end module.

To break the Plug-In:

1. Open the Back-End API Call Module in the Module Builder.
1. Hover over the pluginGetSubmissions Plug-In component.

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

2. Using the toolbar, click the (Settings) button.

NOTE  If you're error handling your own Plug-In, open your Plug-In.

3. Enter a bracket somewhere in the Data Source URL.

4. Click Save.
5. Save your module.

To test that the pop-up error message works:

1. Open your front-end module in Express View.
2. Click the Execute Get Submissions API Button.

You'll see a pop-up with the error message that you set in the ruleShowAPIError Decisions component.

Using this Configuration to Error Handle Multiple Plug-Ins

If you have another module (or more) between your back-end module and your front-end module, use the same setup you learned in this article. The role of the middle module(s) is to pass any Plug-In call's error response back to the front-end module. The Plug-Ins and modules work together, like an assembly line.

Imagine you have a module between the front-end and back-end modules. Think of the natural order of how these modules interact with each other. The end-user takes action on the front-end, which remote executes to the middle module. The middle module then remote executes to the back-end module. There are 3 calls in this scenario, so there are 3 pop-up error messages on the front-end.

Every Plug-In needs an Error Trigger. And, Hidden components must store in the database to carry the error responses to the front-end. You’ll always do error handling for a Plug-In in the module where that Plug-In lives. Then, you'll continue the error handling configuration on any middle module(s). Finally, you'll bring the error responses to the front-end, completing the assembly line.

As an example, say there’s an error in the API call on the back-end. The middle module carries along that error response. The middle module also has its own error handling for its remote execute call. The front-end brings forward both possible error responses from the middle module. That means the front-end module's Plug-In has 2 mapping instances in the Output table. If you have 5 modules working in a row, the front-end module's Plug-In has 4 mapping instances, and so on.

Summary

There are many approaches to error handling in Unqork. As you configure, you'll find the setup that best suits you. In the basic error handling lab (Use Case: Configuring a Pop-Up Error Message), you learned one approach to error handling. The configuration used a Calculator, a Decisions component, and the integratorErrors object. In this advanced use case lab, you learned how to error handle a second way. This configuration uses an Initializer and a Decisions component. And, you learned how to error handle multiple calls at once.

Remember, the goal is to set up error handling on all Plug-Ins. And all error message configuration takes place on the front-end module. From there, any error down the line shows error messages for the end-user in Express View. The end-user stays informed no matter where the error happens.

Lab