Common Troubleshooting Strategies

When unexpected behavior occurs in an Unqork application, begin by describing the issue to the Build Agent in the Module Builder. The agent can often identify the cause of common configuration issues quickly.

These strategies cover manual investigation techniques for complex API failures, unexpected submission data, and behaviors that are difficult to reproduce in production. Some strategies are common to software development in general, and others are specific to Unqork.

For complex issues, contact support.unqork.com.

Google Chrome is Unqork's recommended browser. Some of the following processes are specific to Chrome. This article references DevTools (Inspect), which is built into Chrome.

Checking the API Network Log Using DevTools (Inspect)

This strategy helps determine the API call status code in the Network tab of DevTools. Research the code to understand the cause of any unexpected behavior.

In Unqork, integrations take the form of API calls made through a Plug-In component. endpoints can be external or internal to Unqork. Module saves also occur through API calls.

Accessing the DevTools Network Tab

To open the DevTools Network tab:

1. Click View in App to open the module in Express View.

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

3. Click Inspect. The DevTools open as a panel to the right of the page. To open DevTools directly, press Ctrl + Shift + J (Windows/Linux) or Option + Command + J (Mac OS).

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

As data is submitted in the module, the Network log rows populate with information. Each row represents a resource and displays in chronological order. API calls are the resources to investigate most when troubleshooting.

A common strategy is to watch API calls as they happen while navigating through the application. Note whether each call succeeded, what response the endpoint returned, and whether any error messages appear, and if so, what they say.

Investigating an Unsuccessful API Call

Red text in the Network panel represents an unsuccessful call.

To investigate an unsuccessful API call:

1. View API calls in the Network tab of the DevTools.

2. Select the unsuccessful call. The panel populates with a second menu and details of the call.

3. Click the Headers tab of the second menu.

4. Locate and note the status code.

5. Click the Response tab to get more information on the status code.

When end-users see an error message, they often close and ignore it. However, the status code and the issue behind it are important for troubleshooting. Error messages are often descriptive and useful when investigating a problem.

The quickest way to determine what an error code means is to search for it in a browser. For example, search for "What does [xyz] response code mean?" Say a module on the server side returns a 412 response code. A 412 code suggests that the server-side module execution failed.

Interpreting the Console Output

This strategy lets you determine the timing and order in which components fire. The Console output displays a live feed of the process during a submission. Compare this against the configuration to determine if the order and process are correct. The Console output displays when a rule begins firing and when it ends. If a rule begins but never ends, an issue occurred in the rule logic.

To open the DevTools Console tab:

1. Click UI View to open Express View in the Module Builder.

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

3. Click Inspect. By default, the DevTools panel opens on the right side of the page. To open DevTools directly, press Ctrl + Shift + J (Windows/Linux) or Option + Command + J (Mac OS).

4. At the top of the DevTools panel, click the Console tab.

The Console tab lets you view the Unqork application's submission data. A blue arrow to the left of a blank row at the bottom of the Console's feed indicates the command line. Use this field to query the submission data directly.

Add Console output for a Data Workflow component by setting up Console operators to output specific information. When the module fires, the DevTools Console feed displays each step of the Data Workflow.

If the Console output is difficult to interpret, copy and paste it into the Build Agent for analysis.

Checking Submission Data with a Data Command

This strategy helps confirm submission data using the DevTools Console. A data command displays the submission data currently held in the browser. In Express View, use a data command to check the submission data saved to the browser.

For example, suppose an end-user enters their Social Security Number in a field but the information does not appear in the database. First, verify that they entered the information using a data command. Once the data is confirmed in the browser, determine whether it saves on submission.

To open the DevTools Console tab:

1. Click UI View to open Express View in the Module Builder.

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

3. Click Inspect. By default, the DevTools panel opens on the right side of the page. To open DevTools directly, press Ctrl + Shift + J (Windows/Linux) or Option + Command + J (Mac OS).

4. At the top of the DevTools panel, click the Console tab.

The Console tab lets you view the Unqork application's submission data. A blue arrow to the left of a blank row at the bottom of the Console's feed indicates the command line. Use this field to query the submission data directly.

To run the Unqork Angular command in the DevTools Console tab:

1. At the prompt, enter the following command:

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

2. Press Enter or Return. The submission object displays in the Console.

3. Click the expand arrow to the left of the response in the Console panel. The response begins with {data: {...}}.

4. Expand the data section to display the submission data object.

The Console panel populates with data for the current submission.

To repopulate the most recent command next time the DevTools Console is opened, press the up arrow key.

The Angular command only displays submission data stored in a component through automated or end-user input before the command runs. Data displays even if values were entered without submitting. Data in the Console panel is temporarily stored in the browser.

Reading an Application's Configuration

For straightforward configuration questions like why a component is not firing or how logic is sequenced, describing the issue to the Build Agent is often the fastest first step.

This strategy walks through reading the configuration of an application manually. An application's configuration determines its behavior. Understanding module configuration is a key skill when troubleshooting in Unqork. The goal is to understand how module logic works and how components interact — as inputs, triggers, and outputs.

Say a Calculator component is not firing. Confirm which component triggers the Calculator component and follow the configuration to isolate the behavior.

Determining Component References

To check if another component references a component:

1. Open the module in the Module Builder.

2. Navigate to the component to review.

3. To the right of the component, an icon displays if the component references another component in the module.

4. Click the icon. A modal displays the component's reference relationships. Categories shown depend on the component's role in the module; common ones include Outputs and Output of. Components with inputs or triggers might also display Inputs, Input of, or similar categories.

Reviewing the Application Logic

To review the application logic:

1. Open the module in the Module Builder.

2. Begin with the module's first component, then follow the application logic.

   When previewing the module in Express View, what happens first? An Initializer component might fire, or an end-user might begin the process by entering information.

3. Look at component inputs, outputs, triggers, and trigger types to understand how the configuration works.

4. Perform a side-by-side comparison of the reported behavior versus the expected behavior.

Reviewing the application logic is a flexible process. Instead of a fixed checklist, navigate the unique flow of each application.

Checking a Transform Output Using an API Call

With this strategy, validate a transform output using an API call to determine if the logic works as expected. A transform converts submission data into a different structure. It lets you control the format of data coming into Unqork or data sent to a client.

Say a client does not receive the data they expect. Run the data command to determine whether the data is in the submission. If it is, the next step is to determine why the client did not receive the data. Call the transforms endpoint directly to see the transform output.

To confirm a transform's output:

1. Enter the following URL in the browser, replacing the placeholders with the correct values:

   https://{your-environment}.unqork.io/fbu/uapi/modules/{moduleId}/transforms/{transformId}

2. Press Enter or Return. The transform output returns in the browser.

If the submission includes data but the data does not appear in the transform's output, the issue is in the transform logic. Review the transform's logic to determine the cause.

This step requires authentication as an Administrator in the environment.

Setting up Service Logs for APIs and Remote Executes

This strategy involves customizing service logs for APIs and remote executes. Service logs let you capture request bodies and response bodies to view the details of a call. When a call fails, service logs can help determine why.

For more information, visit Understanding Service Logs.

Setting up Service Logs for External APIs

Service logs store any call made to an API set up in Unqork's Services Administration. Capturing request and response bodies provides more information when troubleshooting a failed call.

Set up logging preferences under the Logging section of Services Administration. Once logging is set up for the Unqork service, the logs save to Unqork's database so they can be queried at any time.

Setting up Service Logs for Remote Executes

Set up service logs to capture the details of remote execute calls. A remote execute is when a module runs on Unqork's server instead of in the end-user's browser. Capturing the request and response bodies of calls can help with troubleshooting. Set up the request and response body log through Unqork's Environment Administration.

The Server Side Execution Request/Response Body Log drop-down includes the following options.

Remote execution, also called server-side execution, is a best practice for application security. Creators with Designer access can see server-side execute logs at: https://{your-environment}.unqork.io/fbu/uapi/logs/services?type=remoteExecute.

The Server Side Execution Request/Response Body Log setting lets you choose what the log captures. Select one of the following options:

• Capture all request/response bodies.

• Do not capture request/response bodies.

• Capture request/response bodies on failure.

To adjust what the log captures:

1. From the Server Side Execution Request/Response Body Log drop-down, select an option.

2. At the bottom of the page, click Save Changes.

Enable this setting even for successful calls; the data sent and received might be incorrect. Having access to the request and response bodies for all calls provides the information needed to troubleshoot any call.

Set up PagerDuty alerts using Environment Administration. When configured, PagerDuty sends alerts when there are errors in the Unqork application. To use the PagerDuty integration, a PagerDuty account is required.

Checking Service Logs Using an API Call

In Services Administration, define which services connect to the API and the level of logging for each service. All the logs save as a collection in the Unqork database. To retrieve service logs, enter the following endpoint in the browser: https://{your-environment}.unqork.io/fbu/uapi/logs/services.

Consider 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 readable way.

Customize the query to locate calls made during a specific time frame, or narrow service logs to remote executes only. The query string can specify the service name, filter conditions, and sorting.

For example, to return service logs for a specific service, enter the following API call in the browser: https://{your-environment}.unqork.io/fbu/uapi/logs/services?serviceName={your-serviceName}.

For more information on query parameter syntax, see api-query-params on GitHub.

If a log response is difficult to interpret, paste it into the Build Agent. The agent can help identify patterns and suggest next steps.

The table below describes each response attribute in a service log:

Testing API Endpoints Using Third-Party Applications

This strategy explains how to use third-party applications like Postman and Insomnia to test API endpoints. These tools let you make API calls outside a specific browser or configuration. Use them to determine whether a failed response is caused by the endpoint itself or by the data sent to it. If the endpoint works when called from Postman, it is likely a configuration issue in Unqork.

Third-party Application Downloads

Download either of the following desktop applications:

• Postman

• Insomnia

Updating Data Using a Module

Sometimes an incorrect submission value prevents the application from proceeding. Instead of reconfiguring the application, update the data for that submission.

Say an insurance application has a Hidden component called applicationStatus. An agent can only review the application if applicationStatus is set to complete. An end-user had trouble uploading an image of their driver's license and emailed it instead, leaving the application as in progress. The unfinished application blocks the agent from reviewing and approving it. Updating the applicationStatus lets work continue without any further steps for the user.

The fastest way to build this module is to describe it to the Build Agent:

Create a module with a Text Field component and a Plug-In component configured to update a specific field in an existing submission using the Update Module Submission internal service. Add a Button component to trigger the Plug-In.

Once built, verify the following configuration before running it.

Entry Component

Use a component type that matches the data type of the field being updated: a Text Field component for text values, or a Number component for numeric values. Set its Property ID to identify the value to update (for example, firstName).

Plug-In Component

In the Inputs table:

firstName is the Property ID of the entry component. {fieldToUpdate} is the name of the field to update in the submission.

Button Component

Run and Verify

1. Click UI View to open Express View in the Module Builder.

2. Enter the value to update in the entry component.

3. Click Submit.

If configured correctly, the button triggers the Plug-In component and updates the submission data.

When updating an array or object's data, the new data overwrites the entire array or object. Contact your Unqork representative with any questions.