Troubleshooting Unqork Applications

When creating or maintaining applications, unexpected behavior can occur. Troubleshooting is the process of identifying what went wrong, locating where it went wrong, and resolving it. This article covers the three core steps used to diagnose and fix issues in Unqork applications.

Before working through these steps manually, describe the unexpected behavior to the Build Agent in the Module Builder. The agent can often identify the cause of common configuration issues quickly.

For especially complex issues, contact support.unqork.com.

Basic Steps of Troubleshooting

Troubleshooting begins when unexpected behavior displays in an application. The starting point can take different forms: an error message, a problem in a downstream system, or something displaying incorrectly.

The basic steps of troubleshooting are:

1. Investigate and Replicate: Understand the context of the unexpected behavior and, if possible, recreate the issue.

2. Isolate: Narrow down the search to isolate the cause.

3. Terminate: Once the cause is identified, fix it.

Use Module Outline in the Module Builder to help diagnose common configuration issues.

Investigate and Replicate

The first step is to understand the system and what is failing. Investigate the unexpected behavior before looking for the root cause. This is especially challenging if the person reporting the issue lacks specific details.

Trace the steps a Creator or end-user could have taken to reach the error. Follow the application's flow and consider which inputs, triggers, or conditions could have contributed to the failure. This context narrows the search before testing begins.

Try different combinations of events and values, noting results at each step.

Consider the following questions when investigating unexpected behavior:

• Do I understand the issue?

• Do I know what is happening?

• What series of events led up to this unexpected result?

• Do I understand what is supposed to happen based on the configuration or requirements?

• Which environment is the end-user in?

• What role does the end-user have?

• Are they using test data or production data?

Confirming that the failure occurs consistently and understanding its context is essential before proceeding.

Replicate the behavior only if doing so will not cause problems in production.

Once the issue is described and replicated, move on to isolating the unexpected behavior.

Isolate

The next step is to narrow down the location of the issue. The key question is: at what point does the actual behavior diverge from what is expected?

One effective approach is to divide the module in half. Duplicate the module and remove the second half. If the error persists, the issue is in the first half; if not, check the second. Continue halving until the location is isolated.

With the location identified, isolate individual factors. Check the details of the application's components. If a Calculator component runs five calculations, work through each one.

When the cause is unclear after narrowing the area, describe the isolated section to the Build Agent. The agent can often surface the root cause without further manual narrowing.

Terminate

Once the cause is identified, resolve it. The change might be minor, like correcting a field value in a Decisions component, or more involved. Make the smallest change that addresses the root cause, then retest before making additional changes.

When one component or configuration does not resolve the issue, consider alternatives. A Calculator component or Initializer component might fit the same goal better than a Decisions component. The Build Agent can also suggest alternative configurations once the cause is known.

After applying a fix, confirm it resolved the issue. Check the data and the page to confirm everything looks as expected. Run the module and repeat the steps from the replication phase. Test different variations to confirm everything still functions as expected.