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:
-
Sending data to an external service that requires a format other than what's used in Unqork (JSON).
-
Receiving data from an external service that only provides data in a format other than JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data..
-
Sending data between Unqork modules using different Property IDs for the same data.
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):
-
XSL XSL (eXtensible Stylesheet Language) is a styling language used to transform and render XML. (XML)
-
NJK (PDF)
-
NJK (XML)
-
NJK (TXT)
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
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. |
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. |
4. | From the Internal Services drop-down, select Execute Transform with Input Data. The Data Source URL and Request Type prepopulate. |
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.
7. | Click Save. |
Adding a Button Component
Next, add a Button component to trigger the Plug-In component.
1. | Drag and drop a ![]() |
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. |
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 ![]() |
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. |
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:
|
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:
|
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. |
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. |
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. |
5. | At the Delete confirmation message, click OK. |