Module Transforms
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 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 Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way.)
-
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 DATA 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 ··· (options) 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 + Add New Transform. |
| 2. | In the Transform Name field, enter a name for your transform. Use this name to reference your transform in your module. |
NOTE Once created, you cannot change the name.
| 3. | Under Type of Transform, select the type of transform you want to use. |
| 4. | In the Transform field, enter your transform. |
| 5. | Click Save. |
| 6. | 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, let's reference your transform in your module using a Plug-In component. Then, configure a Button component to trigger the Plug-In component.
Configure 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 Enter inputs components and actions you want the component to perform. to reference the transform. Then, use the component's Outputs table Enter outputs components and actions you want the component to perform. 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. | Navigate to the component's Data settings. |
| 5. | From the Internal Services drop-down, select Execute Transform with Input Data. The Data Source URL and Request Type autopopulate. |
| 6. | Next to Inputs & Outputs, click Edit. |
| 7. | 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.
| 8. | 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 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.
| 9. | Click Save Component. |
Configure a Button Component
Next, configure a Button component to trigger the Plug-In component.
| 1. | Drag and drop a  Button component onto your canvas, placing it below the pluginExecuteTransformPlug-In component. |
| 2. | In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter btnExecuteTransform. |
| 3. | In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Execute Transform. |
| 4. | Navigate to the component's Actions settings. |
| 5. | Set the Action Type The action performed by the button when selected. to Event. |
| 6. | In the Click Event field, enter the Plug-In component's Property ID. |
| 7. | Click Save Component. |
| 8. | Save your module. |
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. |
|
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 how the transform functions.
To edit a transform:
| 1. | Open your module in the Module Builder. |
| 2. | Click the ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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 Changes. |
| 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 do not 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 does not include the Unqork settings contained in 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 ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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 does not 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··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ drop-down, click Delete for the transform you want to remove. |
| 5. | At the Delete confirmation message, click OK. |
Testing a Transform
To test the transform, open your module in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. and create a submission. Next, use the submission ID in the Transforms modal A modal is a window that appears on top of the content you are currently viewing..
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 ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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. |
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 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 Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way.)
-
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 data 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 ··· (options)) 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 cannot change the 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.
Configure 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 Enter inputs components and actions you want the component to perform. to reference the transform. Then, use the component's Outputs table Enter outputs components and actions you want the component to perform. 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 autopopulate. |
| 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. |
Configure 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 pluginExecuteTransformPlug-In component. |
| 2. | In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter btnExecuteTransform. |
| 3. | In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. 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. |
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 how the transform functions.
To edit a transform:
| 1. | Open your module in the Module Builder. |
| 2. | Click the ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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 do not 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 does not include the Unqork settings contained in 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 ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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 does not 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 ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ drop-down, click Delete for the transform you want to remove. |
| 5. | At the Delete confirmation message, click OK. |
Testing a Transform
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 ··· (options) button. |
| 3. | Select Transforms. Your transforms display in the Active Transforms table. |
| 4. | From the Action ▾ 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. |
