Testing and Troubleshooting Transforms

A transform is a set of rules that converts submission data from one format into another. When creating transforms in Unqork, errors or unexpected outputs might occur.

Before testing manually, describe the transform and the unexpected output to the Build Agent. The agent can often identify syntax errors, mapping mistakes, or configuration issues directly.

Test transforms using the Test Transform section in the transform, or the DevTools Network tab when the transform is applied in a different module. Transform errors typically do not identify where the error occurred, so this article also covers how to identify and resolve common errors.

Testing Transforms Using the Test Transform Section

Some transforms exist in the same module as the submission data; to test these, use the Test Transform section in the transform. If the transform is applied in a different module, use the DevTools Network tab instead.

Before using a transform in production, open the module in Express View using View in App and make a submission. Then copy the submission ID and paste it into the Test Transform section.

To test a transform:

1. In the Module Builder, click View in App.

2. Enter the information in the module.

3. Save the module's submission data.

   Save the module's submission data to the database before copying the submission ID. For example, use a Button component configured to submit the form.

4. Copy the submission ID.

   The submission ID is the middle segment of the three alphanumeric codes in the Express View URL. The URL follows this structure: https://your-environment.unqork.io/{module-id}/{submission-id}/{module-id}.

5. Open the module in the Module Builder.

6. At the top of the Module Builder, click the Definition drop-down.

7. Select Transforms. Existing transforms display in the list.

8. Open the transform to test.

9. Locate the Test Transform section.

10. In the Submission ID field, paste the submission ID.

11. Click Run Test. The Input field populates with the submission data, and the transformed result displays in the Output field.

Testing Transforms Using the Network Tab

When the module where a transform is created differs from where it is applied, use the DevTools Network tab. Switch between the transform, the module where it is triggered, and the output; this lets Creators apply edits and check results in real time.

To test a JSON transform in the Network tab, open three web browser tabs:

Setting Up the Transform Tab

The first tab to open is the JSON transform. Navigate to Transforms through the Definition drop-down in the Module Builder where the transform was created. Make any edits and save the transform to test the changes.

Setting Up the Module Builder Tab

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

Before testing the transform, confirm the Plug-In component is configured correctly. If the configuration is wrong, the 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 to transform.

2. The Plug-In component's Outputs table maps to where the output is stored. For a JSON transform, the output name is jsonData.

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

4. Confirm the Data Source URL is accurate.

5. Click Save.

Setting Up the Express View Tab

In the third tab, use the DevTools Network tab to view results.

To access the Network tab:

1. In the Module Builder, open the module where the input or output transform is triggered.

2. Click View in App.

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

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

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

Once the module runs in Express View, the Network tab populates with results. From the list, select the transformer to view the output. If an error occurs, the transformer displays in red. If the transform Plug-In component is not triggered, the transformer does not appear in the Network tab.

Troubleshooting Common Transform Errors

Transform errors do not identify where an issue occurred. When a transform encounters an error, it stops at the first one.

Configuration Errors

Sometimes a transform does not work due to a configuration error. These issues can occur in the following cases:

• A Plug-In component trigger is missing.

• Entries in the Plug-In component's Inputs or Outputs table are missing or incorrect.

• An internal service is not selected.

Troubleshooting Missing Plug-In Component Triggers

If the Plug-In component is not working, confirm its trigger is configured correctly.

Troubleshooting Inputs and Outputs

Another common configuration error involves the Inputs and Outputs tables in the transform Plug-In component. If incorrect values are entered, the transform returns an error or unexpected data.

If required information is missing from the Inputs or Outputs tables, the transformer displays the Missing POST variable data error in the Network tab. For example, when using Execute with Input Data, the module ID, transform name, and data to transform must all be present in the Inputs table.

If the transform uses a Pre-Request Transform trigger, the Inputs and Outputs do not exist in the Plug-In component. To resolve this error, add the necessary values to the transform.

Troubleshooting Missing Internal Services

An error might occur if no internal service is selected for the transform Plug-In component. In the Module Builder, configure the transform Plug-In component using either the Execute with Input Data or Pre-Request Transform internal service. If neither option is selected, the following error displays in the DevTools Network tab: Cannot POST /.

Syntax Errors

Each data type in a transform follows a specific set of syntax rules. This section covers JSON transform syntax errors. For other data types like XML, no error displays in the Network tab; the transform outputs incorrect data instead.

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. Before running a transform, check the following:

• Transform objects, variables, and arrays use the correct notation.

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

• Capitalization in the transform is correct. JSON is case-sensitive, so an incorrect capital letter will cause an error.

• Keys in key-value pairs are surrounded by double quotes.

Mapping Errors

Mapping errors occur when a transform sends data to the wrong key or field. This can return the Could not parse NJK-transformed data to JSON error.

For example, say a transform has two Nunjucks variables. Nunjucks is a templating language used to write transforms. One variable stores a client name as text, and the other stores their age as a number. If the variables are accidentally switched and assigned to the wrong keys, the transform assigns the wrong values and the data displays incorrectly.

Mapping an array incorrectly also results in a mapping error. When writing Boolean, number, or string variables, single Nunjucks variables might be used. For arrays, the variables must be included 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 returns a transform error, though the specific error or output varies.

Mislabeling Strings

Mislabeling strings in a transform returns an error. Say a JSON transform is written with Nunjucks variables. The Nunjucks variable stores a string value that was not wrapped in double quotation marks. The 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 does not cause an error. Instead, the transform runs and returns incorrect output.

If a transform includes a number value in quotes for a variable, it returns the number value as a string. While the transform runs without an error, it does not return the expected values.

Mislabeling arrays also returns incorrect data. An array can contain string, number, or Boolean values as elements. When writing a JSON transform, arrays must be in a loop. Mapping to an array with a single Nunjucks variable results in an error. But if quotes are added to the variable, the transform does not return an error. Instead, it runs and returns [object Object] for each array element.

Say a transform stores insurance clients and their dependents. In the transform, a single Nunjucks variable maps to an array with the dependents' names. To store the variable as a string, it is written in double quotes. When the transform runs and the transformer is opened in the 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. Test early and often.

Even with the right preparation, errors might still occur. The Build Agent can help diagnose transform issues. Paste the transform and the error message into the agent for analysis. For issues that require manual investigation, apply the investigate, isolate, and terminate approach:

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

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

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

As portions of the transform are removed or added, check syntax before running; a misplaced comma or open bracket can introduce a separate error.

For more information, see Troubleshooting Unqork Applications.