Module Transforms

Estimated Reading Time:  7 minutes

Overview

Working in Unqork, you may need to convert data from one format to another. To do that, you'll use a transform. Transforms are helpful for:

For both sending and receiving data, you'll configure transforms in the Module Builder.

What You'll Learn

In this article, you'll learn about module transforms, and how to create, edit, test, and download them.

What Is a Transform?

A transform is like a set of instructions you give Unqork to reformat your data. First, specify whether the data is coming in or going out of Unqork. Doing so determines the direction of the transform. Then, select the type of transform you want to perform, and choose a programming language compatible with your data's destination. For Input transforms, you can only use JSON because that is what Unqork uses. For Output transforms, you can use (where the type of language is first and the output is in parentheses):

NOTE  For Output transforms, confirm the format needed based on your destination.

Once a transform type is selected, you can write your transform and input any structural changes. For example, you might change Label Text or Property IDs when sending between Unqork modules.

Accessing Module Transforms

A static image displaying how to access the Transforms modal.

You can access transforms from either the Module Builder or Workflow Builder.

To access transforms:

1. Open your module in the Module Builder.
2. Click the ··· (ellipsis) button.
3. Select Transforms.

Creating a Transform

The first step of working with transforms in Unqork is to create one.

To create a transform:

1. Click + New Transform.
2. In the Enter Transform Name field, enter a name for your transform. Use this name to reference your transform in your module.

NOTE  Once created, you can't change this name.

3. Under Direction of Transform select Input or Output depending on the direction of your transform.
4. For an Output type, click the Output tab and select the Type of Transform you want to use.

NOTE  By default, the only available Input type is NJK (JSON).

5. In the Transform field, enter your transform.

A static imaging displaying how to create a transform.

6. Click Save.
7. Click Back to return to the Transforms modal A modal is a window that appears on top of the content you are currently viewing.. Or, click X to return to the Module Builder.

Referencing a Module Transform

Now lets reference your transform in your module using a Plug-In component. Then, configure a Button component to trigger the Plug-In component.

Adding a Plug-In Component

A Plug-In component lets you import information from your transform into your module. You'll use the component's Inputs table to reference the transform. Then, use the component's Outputs table to determine how the data is transformed.

1. Open the module where you created the transform.
2. In the Module Builder, drag and drop a Plug-In component onto your canvas.
3. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas Label Text isn't end-user facing, and only appears in the . fields, enter pluginExecuteTransform.
4. From the Internal Services drop-down, select Execute Transform with Input Data. The Data Source URL and Request Type prepopulate.

A static image displaying how to select the Execute Transform with Input Data Internal Service.

5. In the Inputs Enter inputs components and actions you want the component to perform. table, enter the following:

Property ID

Mapping

'Your Module Name'

formName

'Your Transform Name'

transformName

'The Field to Transform'

data

NOTE  The Property ID column above is unique to your transform, module, and field. Repeat this step for each field you're transforming.

6. In the Outputs Enter outputs components and actions you want the component to perform. table, consider the following:
Transform Type Mapping

Input

Map the information coming out of the transform to fields in your module. This overrides the original information.

Output

Map the information coming from the transform to where you want it to go. For example, TXT or a PDF.

NOTE  The Property ID column reads as returnedData for either transform type. The Mapping column references the Property ID of the component that'll hold your transformed data.

A static image displaying the correct Input and Output syntax to trigger the transform.

7. Click Save.

Adding a Button Component

Next, add a Button component to trigger the Plug-In component.

1. Drag and drop a Button component onto your canvas, placing it below the pluginExecuteTransform Plug-In component.
2. In the Property ID field, enter btnExecuteTransform.
3. In the Label Text field, enter Execute Transform.
4. Set the Action Type The action performed by the button when selected. to Event.
5. In the Click Event field, enter the Plug-In component's Property ID.

A static image displaying how to configure an event click to trigger the Plug-In component.

6. Click Save & Close.
7. Save your module.

Testing a Transform

Before using a transform, you should test it. To test the transform, open your module in Express View and create a submission. Next, use the submission ID in the Transforms modal.

TIP  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/5e13aa4616d385021040e00/5e8769e9c74b570d5e9d88bb/5e12aa4616d38502104.

NOTE  If you have a large module but want to test transforms with only part of the module, create multiple transforms. Then, add the smaller transforms to a parent transform. So, you'd have one transform for part A, one transform for part B, and a parent transform.

To test your transform:

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, enter 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.

A static image displaying how to add a submission ID and test the transform.

Using the Active Transforms Table

If you click Back after creating transforms, all your transforms display in the Active Transforms table. This table displays the following information about your transforms:

Attribute Description

Active Transforms

The name of the transform.

Direction

The direction of the transform. Options include Input or Output.

Type

The type of transform, including the template language and the output format in parentheses:

  • NJK  (JSON): Where the template language is Nunjucks and the output format is in JSON.

  • XSL  (XML): Where the template language is XSL (eXtensible Stylesheet Language) and the output format is in XML.

  • NJK (PDF): Where the template language is Nunjucks and the output format is in PDF.

  • NJK (XML): Where the template language is Nunjucks and the output format is in XML.

  • NJK (TXT): Where the template language is Nunjucks and the output format is in TXT.

Created By

The user that created the transform.

Last Modified

The date and time the transform was created.

Last Modified By

The user that last modified the transform.

Actions

The available actions you can you can take on the transform.

Actions include:

  • View and Edit: Vew transform details and make edits.

  • Download: Download the transform to your computer.

  • Delete: Permanently remove the transform.

Editing a Transform

After creating and testing your transform, you can make changes to it. Once you've created a transform you can only change the Transform block, or what your transform actually does.

To edit a transform:

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

A static image displaying how to edit a transform.

5. Edit your transform as necessary.

NOTE  You cannot edit the transform name after creation.

6. Click Save.
7. Click Back to return to the Transforms modal. Or, click X to return to the Module Builder.

Downloading a Transform

If you restore a previously deleted module, the transforms don’t restore with it. To avoid having to recreate the transform, you can download it as a backup. Then, you can copy and paste it to a new transform.

It's important to note that your downloaded transform includes the transform body only. The file doesn’t include the Unqork settings that go with it. To restore your Unqork settings, set them up as you would a new transform.

To download a transform:

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 Download for the transform you want to download.

A static image displaying how to download a transform.

5. Locate the file in the downloads folder of your computer.

Deleting a Transform

If you no longer need a transform, you can delete it. Keep in mind that deleting a transform doesn't delete the components that reference it. You still need to delete any references to the transform from your module.

To delete a transform:

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 Delete for the transform you want to remove.

A static image displaying how to delete a transform.

5. At the Delete confirmation message, click OK.