Testing and Troubleshooting Transforms

Overview

As you create transforms in Unqork, you may come across errors or unwanted outputs. When this happens, you'll want to 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

Sometimes, your transform and your submission data occupy the same module. The Transforms tab testing tool tests transforms sharing the same module as your submission data. So, if your application only applies its transform to a single module, this testing tool is ideal!

Most applications though use more than one module. That means your transform may be in a different module than your submission data. Here's where the DevTools Network tab comes in. You can use this tab on your module preview to test the output of your remote transforms.

After testing your application, you may need to fix errors through troubleshooting. When troubleshooting your transforms, errors can be hard to identify. Transform errors won't tell you where the error occurs. So, finding a solution isn't always straightforward. To help you, this lesson covers strategies you can use to troubleshoot your transform. You'll also learn how to identify and resolve common errors you may get when using transforms.

What You'll Learn

In this article, you'll learn:

• How to test transforms using the testing tool.

• How to test transforms using the Network tab.

• How to troubleshoot transform errors.

• How to identify and fix common transform errors.

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. Remember, most applications in Unqork function across several modules. If this is true of your application, you'll test your transform using the DevTools Network tab.

Before using a transform on the same module as your submission data, you'll test to see if it works. To do this you'll first open your module in Express View and make a submission. Next, copy the submission ID and paste it into the Transforms screen.

To test a transform on the Transforms tab:

1.

In the Module Builder, click the Preview Module button.

2.

Enter the information in the module.

3.

Save your module's submission data.

4.

Copy the submission ID.

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.

Expand the Unit Testing panel.

6.

In the Submission ID field, paste your submission ID. Submission data from the module populates in 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 make in Unqork will have more than one module. That means the module where you create your transform may be different from where you want to apply it. So, testing on the Transforms tab isn't the best option. Instead, you'll use the DevTools Network tab to test your transform. But, to do that, you'll need to set up your module to run the test accurately.

One way to test your transform is to alternate between your transform, the module you trigger it in, 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.

Say you have an application that consists of multiple modules. You have an Input JSON transform that you want to apply to submission data on a different module. To test your JSON transform on the Network tab, you'll use three web browser tabs. These tabs let you see the direct outputs of your transform and transform triggers.

To test your transform on the Network tab, you'll use the following tabs on your web browser: 

Web Browser Tab	Description
Transform	Use this tab to edit your transform on the Transforms tab of the Module Builder.
Module Builder	Use this tab to reference the module where your Plug-In component calls your data and transform.
Express View	Use this tab to see your transform test results. You'll use the Preview of the Module Builder to do that.

Now, let's review how you can set up and use each tab to test your JSON transform.

Setting Up Your Transform Tab

The first tab to have open when testing transforms across modules is your JSON transform. Navigate to the Transforms tab on the module where you created your JSON transform. Here, you can make edits to your transform. Once you save your transform, you can test the changes you made right away.

Setting Up Your Module Builder Tab

The second tab to have open is the module with the Plug-In that triggers your transform. For this example, let's configure your Plug-In using the Execute with Input Data trigger.

TIP  If you're starting from scratch and don't have this module set up yet, you'll want to do that first.

Before you test your transform, double-check that your Plug-In has the right configuration. If the configuration is incorrect, your transform won't work as expected.

NOTE  This checklist applies to Execute with Input Data triggers. You can also test Pre-Requests on the Module Builder. But, Pre-Request triggers have the inputs and outputs built into the transform. So, you won't test Pre-Requests using the Plug-In's Inputs or Outputs tables. Instead, you must make changes to the transform itself.

For Execute with Input Data triggers, check the following: 

1.

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

2.

Your Plug-In's Outputs table maps to where your output will get stored.

3.

Your Internal Service is set to your trigger type. For this example, it's set to Execute with Input Data.

4.

Your Data Source URL is accurate.

Setting Up Your Express View Tab

Now that you have tabs open to your transform and your submission data module, you'll want a tab to see your results. To do that, you'll use the DevTools Network tab.

Here's how you can access the Network tab: 

1.

Open the module where you trigger your input or output transform.

2.

Click Preview Module in the Module Builder.

3.

Open the DevTools Network tab.

Once your module runs in the Express View preview, the Network tab populates with your results. From the list, you can select your transformer and see the output. If an error occurs, your transformer appears red. If your transform Plug-In isn't triggered, then the transformer won't appear on the Network tab.

Troubleshooting Common Transform Errors

Remember, understanding what causes transform errors isn't easy. That's because transform errors don't tell you what causes them or where they occur. 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 doesn't work the way you want it to due to a configuration error. This can happen for the following reasons: 

• Missing Plug-In trigger.

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

• Missing Internal Service.

Troubleshooting Missing Plug-In Triggers

A common problem end-users experience is their transforms not triggering. Remember, you trigger your transforms with the Plug-In component. But, the Plug-In often needs a trigger to work. If your Plug-In isn't working, check that your trigger's configuration is correct.

Troubleshooting Plug-In Inputs and Outputs Tables

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

Another error occurs if you leave information out of your Inputs or Outputs tables. Leaving information out causes the transformer in your Network tab to return the error: Missing POST variable data.

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

Let's say you want to use a transform and use an Execute with Input Data trigger. To successfully run your transform, your Inputs table needs the module ID, transform name, and data you want to transform. You accidentally skip over the data Input 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.

Troubleshooting Missing Internal Services

You may receive an error by not selecting an Internal Service for your transform Plug-In. In the Module Builder, you can trigger your transform 2 different ways. You can use Execute with Input Data or Pre-Request Transform Internal Services. If you don't 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 how to write them. If a transform isn't written right, it'll return an error. For this article, you'll learn about errors that occur with JSON transform syntax. For other languages, such as XML, an error message won't appear on the DevTools Network tab. Instead, the transform outputs incorrect data.

TIP  For more information about JSON syntax, search Writing Transforms Using JSON and Nunjucks in our In-Product Help.

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. Remember to 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 between quotes as a string.

Mapping Errors

Another type of error or incorrect output you may encounter are mapping errors. As you write your transform, check that your mapping values match the intended key (or field). When you map to the wrong variable, you may enter the wrong data type. Doing so returns a Could not parse NJK-transformed data to JSON error. If you aren't careful, you may assign the wrong values to the wrong places.

Let's return to our insurance client example. In your transform, imagine you only included one Nunjucks variable for the client and another for their age. The first variable would be a string since it's text, while the second would be a number value. 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 may 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. Let's go over a few Data Type errors you may encounter.

Mislabeling Strings

Mislabeling strings in your transform returns an error. Let's say you're writing a JSON transform with Nunjucks variables inside of it. Your Nunjucks variable stores a string, but you forget to write 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 won't. 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 won't return the values you expect.

Mislabeling arrays also returns incorrect data. Your array can contain string, number, or Boolean values as array elements. Remember, 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 won't return an error. Instead, your transform runs and returns [object Object] for each array element.

Let's look at an example. 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 dependent's names. To store the variable as a string, you 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.

Troubleshooting Transforms Best Practices

When writing transforms, troubleshooting an error or an incorrect output can be a challenge. As you write your transforms, we recommend testing early and often. This helps avoid larger troubleshooting issues downstream.

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.

TIP  For more information about troubleshooting in Unqork, search for Introduction to Troubleshooting in our In-Product Help.

Let's break down how you can use these steps to troubleshoot your transforms. First, you'll want to Investigate and Replicate. That means learning about what is causing the error or incorrect output. To do that, review the different error types we've covered in this article. If possible, try and recreate any issue you think is causing the problem.

If you're not able to identify the problem, try and Isolate the issue. To do that, we recommend running 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.

NOTE  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.