Common Troubleshooting Strategies

Overview

Unqork has common strategies to use when troubleshooting. We’ve narrowed it down to what’s most applicable across various applications. We’ll suggest some of the same strategies for many of the issues you’ll encounter. Some of the strategies are industry standards, and the others are specific to Unqork. With practice, you'll easily pinpoint what strategy to use with an issue. Also, you'll gravitate toward your preferred troubleshooting approaches. Remember; everyone has their own style.

For especially tricky issues, reach out to support.unqork.com. 

What You'll Learn

In this article, you'll learn how to:

• Check API Network Log using DevTools (inspect).
• Interpret Console output.
• Check submission data with a data command.
• Read through the configuration of an application.
• Check transform output.
• Set up service logs for APIs and remote executes.
• Check service logs.
• Test API endpoints using third-party applications.
• Update data using a module.
• Use the server-side Debugger Tool.

NOTE  Google Chrome is Unqork’s recommended browser. Some of the following processes are specific to Chrome. We reference DevTools (Inspect), which is native to Chrome.

Checking API Network Log using DevTools (Inspect)

Using this strategy, you’re checking the API (application programming interface) call status code in the Network Tab of DevTools. From there, you’ll research the code to get details on the unexpected behavior.

One aspect that may need troubleshooting is configuring integrations. Integrations come in the form of API calls. At Unqork, we use plug-ins to make API calls to various endpoints. An endpoint could be external, or it could be an Unqork internal API. When you save a submission, the save occurs using API calls back and forth.

Viewed via Express View, the DevTools Network tab shows the calls made to various endpoints.

Accessing the DevTools Network Tab

To go to the DevTools Network tab:

A common strategy is to watch those API calls as they happen and while you’re going through the application.

From there, you can ask yourself some questions:

• Is the call successful?
• What response is the endpoint returning?
• Is there an error message? If yes, what does it say?

Investigating an Unsuccessful API Call

Red text in the Network panel shows an unsuccessful call.

To investigate an unsuccessful API call:

When users see an error message, they'll sometimes close it without more research. We recommend that you read and dig into these responses. Error messages are descriptive and can tell you what and where a problem lies.

There are a couple of common error codes that you’ll see when navigating Unqork. They’re pretty standard in the industry. A great strategy is to Google these error codes. Copy the response code and Google, “What does [xyz] response code mean?”

TIP  Let’s say you’re working on the server-side execution of a module and you get a 412 response code. A 412 code means that something on the server-side module failed.

Interpreting the Console Output

This strategy shows you how to check the timing and order of how your components fire. The Console output is a live feed of what's happening during a submission. Having access to this output is great because you can see which components trigger and in what order. Then, you can compare against the configuration to see if anything doesn’t match. You’ll find Console output in the DevTools Console tab.

To open the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. tab:

The Console tab is a live preview of your submission data. A blue arrow to the left of a blank row at the bottom of the Console's feed indicates the Console's command line. It's here that you can enter commands to get more data details.

As components fire, the Console panel tells you what components have fired and in what order. You'll compare the Console panel to the module's configuration. This comparison helps you see any inconsistencies. The Console output shows you when a rule begins firing, and when it ends. So, if you see a beginning rule without a followup end rule, you'll know something in the rule logic is wrong.

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. It's here that you'll enter commands to get more submission details. We'll cover that in the next strategy.

TIP  You can also add Console output for a data workflow call. Set up every step of a data workflow to output a piece of information. Then, when you fire the module, the Console feed shows you which step you’re at in a data workflow. 

Checking Submission Data with a Data Command

This strategy helps you check your submission data using the DevTools Console. A data command (or Angular command) shows you how the data in the browser varies from what persists (gets saved) in the database.

In Express View, you can use a data command to check the submission data saved to the browser. You'll check submission data using the DevTools Console.

Use case: Let's say your client enters their Social Security Number (SSN) in a field, but their information doesn't show in the database. First, you'll verify that they entered the information. You'll do this using a data command. Once you confirm that the data is in the browser, you'll check if the data saves on submission. First, you'll need to access the Console tab of DevTools.

To open the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. tab:

The Console tab is a live preview of your submission data. A blue arrow to the left of a blank row at the bottom of the Console's feed indicates the Console's command line. It's here that you can enter commands to get more data details.

To run the Angular command The Angular command, or data command, is a tool that displays submission data in a browser's developer console. In Express View, enter the following command in the devtool console: angular.element('.unqorkio-form').scope().submission in the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. tab:

angular.element('.unqorkio-form').scope().submission

3.

Click the solid drop-down arrow to the left of the response in your Console panel. The response starts with {data: {...}.

4.

Expand the data section to display your submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. object.

TIP  Next time you open the DevTools Console, you can press the up arrow key on your keyboard to repopulate the Angular Command.

NOTE  The Angular command only displays the submission data entered before the command runs.

The Console panel populates with data for the current submission. The data shows, even if you type something without submitting the information. The Console panel's data temporarily stores in the browser.

Reading an Application's Configuration

This strategy walks you through reading the configuration of an application. The application’s configuration shows you how the application should behave. Then, you’ll compare the expected behavior to actual data.

Understanding module configuration is a key skill when troubleshooting in Unqork. The goal is to understand the logic of how the module works. You need to understand basic components and their configuration. It’s also important to know how the components interact with one another. For instance, many components have other components as their input or output.

Let’s say a Calculator component isn’t firing. You could check which component fires the calculator. Then, read through the configuration to isolate the behavior.

Checking for Component References

To check if another component references your component:

Reviewing the Application Logic

To read through the application logic:

Reading through application logic is a dynamic process. Rather than a step-by-step checklist, you’ll follow the unique flow of each application.

Checking a Transform Output Using an API Call

With this strategy, you'll check the transform output using an API call. Checking the transform lets you verify the logic works as expected.

A transform is something you add to a module to convert submission data to a different structure. A transform lets you control the format of data coming in, or data sent to a client. Sometimes, there can be an error in a transform.

Let's say a client doesn't receive the data they expect. As a troubleshooter, you could first run the data command to see if the data is in the submission. If the data is in the submission, the next step is to figure out why the client didn't receive the data. If there's a transform between Unqork and the client, the issue may live there.

The next step is to run the submission data through the transform to see what output the client sees. Then, you can make a call to this endpoint, specifying the right submission and right module.

To check a transform’s output:

The output of that transform returns in the browser. If the data is in the submission but not in the output of the transform, you’ve isolated the issue. There’s something wrong with the transform logic. Or, there may be a misunderstanding of what the requirements are. 

From there, you’ll look at the logic of the transform. Checking the transform's logic should help you pinpoint the issue.

NOTE  These steps assume that you’re authenticated as an administrator in the environment.

TIP  Visit developers.unqork.io for other Unqork API specifications.

Setting up Service Logs for APIs and Remote Executes

This strategy walks you through customizing service logs for APIs and remote executes. You can set up logging preferences to log request bodies and response bodies. Request and response bodies show the details of a call. This information makes troubleshooting easier. When a call fails, service logs can show you exactly why that call failed.

We'll walk through how to set up service logs for APIs and remote execute calls. Then, we'll talk about how to return those service logs.

Setting up Service Logs for External APIs

Service logs log any call you make to an API that you've set up in Unqork's Services Administration. By capturing request and response bodies, you'll have more information to pull from when troubleshooting a failed call.

You'll set up logging preferences under the Logging section of Services Administration. Below, we've documented what these options mean and how to use them.

Once you set up logging for your Unqork service, you're good to go. The service logs save to Unqork's database and you can query the logs at any time. Next, let's set up service logs for remote execute calls.

Setting up Service Logs for Remote Executes

You can also set up service logs to capture the details of your remote execute calls. Remote executes are when a module executes on Unqork's server. You have flexibility with what you capture in these logs. Capturing the request and response bodies of your calls makes future troubleshooting easier. You'll set up the request and response body log through Environment Administration.

Let's look at the options for the Server Side Execution Request/Response Body Log drop-down.

We recommend choosing Capture all request/response bodies. Even if a call is successful, the data to and from may be incorrect. Having access to the request and response bodies for all calls gives you the information you need to troubleshoot any call.

Now that you have service logs saving to the database for your remote executes, let's go over how to find the service logs.

NOTE  You can also set up PagerDuty alerts from Environment Administration. When configured, PagerDuty sends alerts when there are errors in your Unqork application. To use the PagerDuty integration, you must have your own PagerDuty account.

Checking Service Logs Using an API Call

With this strategy, you’ll check service logs to see the status of API calls and remote execute calls.

NOTE  We recommend installing a Chrome extension that formats JSON. Without a JSON formatting extension, service logs return as long lines of text. A Chrome extension organizes the service logs in a user-friendly way.

In Services Administration, you define what services (APIs) integrate with your API. You also define the level of logging you want for that service. You can choose whether you want to log the request and response bodies for that service’s calls. Service logs show you the results of API calls for these services and for server-side calls. All the logs save to a collection in our database called a service log. Let's cover what gets captured in service logs.

Below, we've shared a description of each response item you'll see in a service log.

To get back service logs, you'll use the following endpoint: /fbu/uapi/logs/services.

You can customize your search. Maybe you only want to query failed calls. Perhaps you want to find calls made during a certain timeframe. Or, maybe you want to narrow your service logs down to remote executes only. Filtering operators let you customize any search. The query string can specify the service name, filter conditions, and sorting.

For example, to return service logs for a certain service, you'll enter the following API call into your browser: /fbu/uapi/logs/services?serviceName={serviceName}. Then, you’ll see the response for the service you queried.

To view your filtering options, go to the following link and scroll to the Filtering operators table: https://github.com/loris/api-query-params.

Testing API Endpoints Using Third Party Applications

This strategy explains how to use Postman/Insomnia to test API endpoints.

Postman and Insomnia are third party applications. They let you make API calls outside a specific browser or specific configuration. These applications can be helpful if you’re getting a failed response to an endpoint. This step is especially useful in deciphering vague error messages. 

These applications help you discover if the issue is with the endpoint or with what you’re passing in.

If the endpoint works when called from Postman, it's likely you have a configuration issue.

Let's say the API call is still unsuccessful after entering the endpoint into Postman. You now know the Unqork configuration is working, and the issue lives elsewhere

Third-party Application Downloads

• Download the Postman desktop application here: https://www.postman.com/.
• Download the Insomnia desktop applicaton here: https://insomnia.rest/.  

Updating Data Using a Module

Sometimes, a submission can’t move forward because a piece of data is set to the wrong value. Instead of redoing the configuration, you can update the data for that submission. This strategy saves you from redoing the whole configuration.

Use case: Imagine you have an insurance application with a Hidden component called applicationStatus. Your agent can only review the application if applicationStatus is set to ‘complete.’ A client has an issue uploading an image of their driver’s license. So, instead of uploading the image, they email it to your agent. Your application is still ‘in progress.’ The unfinished application blocks your agent from reviewing and approving the application. You'll use a module to help your agent move forward with onboarding the client. If you update the applicationStatus, work can continue without any further steps for the client.

To use a module to update submission data:

Configure an Entry Component

You'll need a field that accepts a text or number entry. Make sure the component you choose relates to the data type of the submission field you're updating. Let’s say you want to update a field called ‘data.name’, and that field stores as a string. Use a Text Field component. For a numeric value, you'll use a Number component.

Configure a Plug-In Component

Configure a Button Component

After adding these 3 components, your module looks like this:

Updating the Data for the Submission

To complete the update, you'll:

If you configured the module correctly, the button triggers your Plug-In. The Plug-In updates the data for the submission you specified.

NOTE  When you update an array or object’s data, the new data overwrites the entire array or object. Please reach out to your Unqork representative with any questions about this functionality. 

Using the Server-Side Debugger Tool

This strategy lets you mimic a submission's remote execution without going through the workflow. The Debugger Tool is a great way to test your module while you build it.

Let’s say you have a button for users to click in your end-user application. The button triggers a Plug-In, which executes another module via remote execution. The module that’s executed remotely has an API call. The call populates data back into your submission. The Debugger Tool simulates the module’s remote execution without the end-user flow.

To use the Debugger Tool:

You can learn more about the Debugger Tool in our In-Product Help.