Testing and Troubleshooting Transforms

As you create transforms in Unqork, you might come across errors or unwanted outputs. When this occurs, you must test or debug your transforms. In this article, you'll learn about testing your transforms using the following:

• Transforms Tab Testing tool

• DevTools Network tab

Transform errors typically do not tell you where the error occurred. So, finding a solution is not always straightforward. In this article, you’ll learn how to identify and resolve common errors you might experience when using transforms.

Testing Transforms Using the Testing Tool

Some transforms exist on the same module as your submission data. To test these transforms, you'll use the Transforms tab. Most applications in Unqork function across several modules. If that is the case for your application, you'll test your transform using the DevTools Network tab.

Before using a transform, it’s best to test it. You'll begin by previewing your module in Express View and making a submission. Next, copy the submission ID and paste it into the Transforms screen.

To test a transform in the Transforms tab:

1. In the Module Builder, click Preview.

2. Enter the information in the module.

3. Save your module’s submission data.

   You can save your module’s submission data to the database using a Button component.

4. Copy the submission ID.

   The submission ID is the middle of the three alphanumeric codes in the Express View URL. You can see a sample submission ID bolded in the following URL: https://trainingx.unqork.io/695e7de3bef079c75a3a72a8/5e8769e9c74b570d5e9d88bb/695e7de3bef079c75a3a72a8.

1. Open your module in the Module Builder.

2. Click the (ellipsis) button.

3. Select Transforms. Your transforms display in the Active Transforms table.

4. From the Actions drop-down, click View and Edit for the transform you want to test.

5. Scroll down and expand the Unit Testing panel.

6. In the Submission ID field, paste your submission ID. Submission data from the module populates the Input field.

7. Click Run Test. The transformed data displays in the Output field.

   

Testing Transforms Using the Network Tab

Most applications you'll create in Unqork contain more than one module. Meaning, the module where you create your transform might be different from where you want to apply it. Testing using the Transforms tab is not the best option. Instead, you'll use the DevTools Network tab to test your transform.

One way to test your transform is to alternate between your transform, the module where you trigger it, and the output. That way, you can easily apply the edits you make to your transform to your module. Then you can test your transform outputs in real-time.

To test your JSON transform in the Network tab, you'll open three web browser tabs. These tabs let you see the direct outputs of your transform and transform triggers.

Setting Up Your Transform Tab

The first tab to open when testing transforms across multiple modules is your JSON transform. Navigate to the Transforms tab in the Module Builder where you created your JSON transform. Make any edits you want and save your transform to test the changes.

Setting Up Your Module Builder Tab

The second tab is the module with the Plug-In component that triggers your transform. Open this module in the Module Builder. For this example, let's configure your Plug-In component using the Execute with Input Data internal service.

Before you test your transform, ensure your Plug-In component has the correct configuration. If the configuration is incorrect, your transform will not work as expected.

For the Execute with Input Data service, check the following:

1. The Plug-In component's Inputs table maps to the correct transform module ID, name, and data you want to transform.

2. The Plug-In component's Outputs table maps to where your output is stored.

   The name of the output of your transform depends on the type you select. For this example, if you chose a JSON transform, the output would be jsonData.

3. From the Internal Service drop-down, select Execute with Input Data.

4. Confirm the Data Source URL is accurate.

   

5. Save your module.

Setting Up Your Express View Tab

To add the final tab to see your results, you'll use the DevTools Network tab.

Here's how to access the Network tab:

1. Open the module where you trigger your input or output transform in the Module Builder.

2. Click Preview.

3. Right-click anywhere on the Express View screen.

4. Click Inspect. A panel opens in your browser.

5. At the top of the panel, click the Network tab.

Once your module runs in the Express View, the Network tab populates with results. From the list, you can select your transformer and view the output. If an error occurs, your transformer displays with a red color. If your transform Plug-In component is not triggered, the transformer does not display in the Network tab.

Troubleshooting Common Transform Errors

Transform errors do not identify what the issue is or where it occurred. When your transform experiences an error, it'll stop functioning. If your transform has more than one error, it'll stop at the first error it encounters.

To help you with this process, let's go over how to identify and fix common transform errors.

Configuration Errors

Sometimes your transform does not work due to a configuration error. These issues can occur when the following happens:

• A missing Plug-In component trigger.

• Missing or incorrect entries in the Plug-In component's Inputs or Outputs table.

• A missing internal service.

Troubleshooting Missing Plug-In Component Triggers

Transforms are triggered using the Plug-In component, but the component often needs a trigger to work. If your Plug-In component does not work, check that your trigger's configuration is correct.

Troubleshooting Inputs and Outputs

Another common configuration error relates to your transform Plug-In component's Inputs and Outputs tables. If you enter incorrect values into your Inputs or Outputs tables, the transform will return an error or unexpected data.

Another error occurs if you do not enter all the required information in your Inputs or Outputs tables. Excluding information causes the transformer in your Network tab to return the error: Missing POST variable data. Let's say you want to use a transform and the Execute with Input Data internal service. To successfully run your transform, you enter the module ID, transform name, and data you want to transform in the Inputs table. But you accidentally exclude the input data and complete the rest of your transform. Then, you run your transform and check the DevTools Network tab. After you select the transformer, you'll see the Missing POST variable data error.

If your transform uses a Pre-Request Transform trigger, your Inputs and Outputs don’t exist in the Plug-In component. To resolve this error, you'll need to add the necessary values to your transform.

Troubleshooting Missing Internal Services

You might receive an error if you do not select an internal service for your transform Plug-In component. In the Module Builder, you can trigger your transform in two different ways, using the Execute with Input Data or Pre-Request Transform internal services. If you do not select one of these options, you'll receive the following error on the DevTools Network tab: Cannot POST /.

Syntax Errors

You can write transforms according to your data type. But each data type follows a set of rules for writing it. If a transform is not written correctly, it'll return an error. This article reviews errors occurring with JSON transform syntax. For other languages, like XML, an error message does not display in the DevTools Network tab. Instead, the transform outputs incorrect data.

For more information about JSON syntax, review the How to: Write Transforms Using JSON and Nunjucks article.

If a JSON transform has incorrect syntax, it returns the Could not parse NJK-transformed data to JSON error.

Most syntax errors are simple mistakes. Always check the following before you run your transform to avoid these errors:

• Your transform objects, variables, and arrays use the correct notation.

• Each line that contains a value ends with a comma. The exception is if the value is the last item in an object or array.

• The use of capitalization in your transform. JSON is case-sensitive, which results in an error if written incorrectly.

• Keys in key/value pairs are surrounded by quotes as a string.

Mapping Errors

Another type of error or incorrect output you might encounter is mapping errors. As you create your transform, check that your mapping values match the intended key (or field). When you map to an incorrect variable, you might enter the wrong data type. Doing so returns a Could not parse NJK-transformed data to JSON error.

In our insurance client example, imagine you only included one Nunjucks variable for the client and another for their age. The first variable would be a string because it’s text, while the second is a number. But, say you accidentally mixed these variables up and attributed them to the wrong keys. Your transform would assign the wrong values, and your data would return incorrectly.

Mapping an array incorrectly also results in a mapping error. When writing Boolean, number, or string variables, you might use single Nunjucks variables. For arrays, you must include the variables in loops to avoid a mapping error. Referencing an array with a single Nunjucks variable returns the Could not parse NJK-transformed data to JSON error.

Data Type Errors

Writing variables, objects, or values in the wrong data type also returns a transformer error. The type of error message or incorrect output you'll get from a data type error varies. There are a few data type errors you might encounter.

Mislabeling Strings

Mislabeling strings in your transform returns an error. Let's say you're writing a JSON transform with Nunjucks variables. Your Nunjucks variable stores a string, but you forgot to include it in double quotation marks. Your transform breaks and returns a Could not parse NJK-transformed data to JSON error.

Mislabeling Numbers, Booleans, or Arrays

Forgetting to add quotes to a string value returns an error. But adding double quotes to a number or Boolean value will not. Instead, the transform runs and returns an incorrect output.

If a transform includes a number value in quotes for a variable, it'll return the number value as a string. While your transform runs without an error, it will not return the values you expect.

Mislabeling arrays also returns incorrect data. Your array can contain string, number, or Boolean values as array elements. When you write a JSON transform, arrays must be in a loop. Mapping to an array with a single Nunjucks variable results in an error. But if you add quotes to your variable, your transform will not return an error. Instead, your transform runs and returns [object Object] for each array element.

Say you write a transform that stores insurance clients and their dependents. In the transform, you use a single Nunjucks variable to an array with the dependents’ names. To store the variable as a string, you’ll write the variable in double-quotes. Then, you run your transform. When you open the transformer on your DevTools Network tab, it returns [object Object] for each element.

Best Practices

When writing transforms, troubleshooting an error or incorrect output can be a challenge. As you write your transforms, test early and often.

But, even with the right preparation, you may still encounter errors. To help, we have some basic steps you can follow:

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

2. Isolate. Narrow down your search to isolate where the issue lives.

3. Terminate. Now that you know what's causing your issue, you can fix it.

   For more information about troubleshooting in Unqork, review our Troubleshooting Unqork Applications article.

First, you'll want to Investigate and Replicate. That means learning about what is causing the error or incorrect output. Review the different error types covered in this article. If possible, try to recreate any issue you think is causing the problem.

If you're not able to identify the problem, try and Isolate the issue. Run smaller parts of your transform. If no error occurs on the part of the transform you run, move on to another. If you can isolate where the issue lies in your transform, you can easily resolve it.

As you take out or add portions of your transform, be mindful of syntax before you run it. A misplaced comma or open bracket could cause another error to occur.