Transformation Options 2022.1.x

Overview

This guide will cover the options available when working with JSON Schema Transformations (JSTs) in the Gen 1 and Gen 2 workflow canvases of Itential Automation Platform (IAP). The steps involved in selecting JST options for the Gen 1 canvas will be discussed first, followed by the options that are available in the Gen 2 canvas.

Create Workflow

From the IAP home page:

1. Select Automation Studio from the left navbar. The application screen displays.

2. Click + Create a Workflow from the Quick Start card. The Create dialog opens.

   Figure 1: Automation Studio

3. Workflow is pre-selected from the dropdown list. Enter a name (required) for the workflow.

4. Select the appropriate IAP canvas (Gen 1 or Gen 2) and then click Create. The workflow canvas displays.

   Figure 2: Create Workflow

GEN 1 Workflow

To add a JST in the Gen 1 Workflow canvas:

1. In the Search bar (top-right corner), type JST to locate the transformation task.

2. Click the plus (+) sign to the left of the task. This will add a new JST task labeled JSON Transformation to the Gen 1 canvas.

   Figure 3: Add JST Task (Gen 1)

3. Connect the JST task to the Start and End tasks. Transformation tasks can be connected to any two tasks that require you to transform data due to different data formatting requirements​. You can also hover over the JST task to display the tooltip.

   Figure 4: Connect JST Task (Gen 1)

4. Double-click the JSON Transformation task. Then edit the incoming variables.

   Figure 5: Edit JST Task (Gen 1)

5. Select the appropriate options (see table below) you would like to use prior to running your transformation.

   Option (Gen 1)	Description
   Mask Incoming Schema	This option is available on all tasks. It encrypts incoming variables and displays them as asterisks in Jobs (formerly Job Manager).
   Mask Outgoing Schema	This option is available on all tasks. It encrypts outgoing variables and displays them as asterisks in Job Manager.
   Extract Output	This option only applies if you have a single outgoing schema. It removes the wrapper object from the output and returns only the value of that property.
   Validate Incoming	Validates your input. Checks if the input is the correct type and compatible with any keywords set in that incoming schema i.e. enum or const.
   Revert To Default Value	Enables use of a default keyword. Default values from the incoming schemas will be used whenever a key/incoming data value is not provided. If an outgoing schema has a default value, an incoming schema is assigned to it. If the incoming schema does not have a default defined, then the default for the outgoing schema will be used. If an outgoing schema has a default value defined, and nothing is assigned to it, then the default values will be in the transformation output.

6. Click Save and you will return to the Gen 1 Workflow canvas.

7. Click the Start button (top-right) to run the transformation.

   Figure 6: Run JST (Gen 1)

GEN 2 Workflow

Gen 2 workflows provide two methods for working with JSTs:

• The Transformation workflow task, which is used in the same manner as other workflow tasks.
• The JST on Transition feature, which attaches a JST directly to a transition between two tasks in a workflow.

Both methods for working with JSTs are described in this section.

Using the Transformation Task

To add a JST in the Gen 2 Workflow canvas by using the transformation task:

1. Select Gen 2 in the dialog and click Create. A relatively blank Gen 2 canvas then displays that contains a Start and End task.

   Figure 7: Create Workflow (Gen 2)

2. When a Gen 2 workflow is first created, a New Node box is already provided. This is an empty node and needs to be populated with an actual task item.

3. Click the New Node box on the Gen 2 canvas.

4. Go to the Task Menu Sidebar on the right side of the screen. This area contains a list of nodes and tasks that can be used in the Gen 2 workflow.

5. In the Search bar at the top, type JST to locate the transformation task.

6. Click the transformation task and observe that the "New Node" on the canvas has been replaced with the transformation task. Also notice that the Task Menu Sidebar is now replaced with details and configuration options for the transformation task.

7. Click Save to retain changes to the Gen 2 Workflow.

   Figure 8: Save Workflow (Gen 2)

8. Click the transformation node to select options.
9. On the Details tab, you can select the Mask Outgoing Variables option.
10. Click the Options Tab to select Validate Incoming or revertToDefaultValue, as required. Details for all JST options in Gen 2 workflows are referenced in the table below.

11. Click the Save icon (floppy disk) to retain your JST options.

12. Click the Start button to run the workflow.

    Figure 9: Icons to Save and Run (Gen 2)

Using the JST on Transition Feature

Using the JST on Transition feature allows you to utilize a JST in your Gen 2 workflow without having to use a separate task. Instead, a JST is attached to a transition between two tasks, allowing data to be seamlessly transformed as it flows between them.

To add a JST to a transition from the Gen 2 workflow builder:

1. Hover your cursor above the desired transition to reveal a circular menu button (three stacked dots). Select this menu button.

2. Select Add JST from the transition context menu that appears (Figure 12) to open the JSON Schema Transformation window.
   
   

   Figure 10: Add JST to a Transition

   

   
   

3. Use the JSON Schema Transformation window to construct a JST in the same manner that you would when using JST Designer.

4. Select the Save button located at the bottom-left corner of the JSON Schema Transformation window (Figure 13) to apply your JST to the transition.
   
   

   Figure 11: JSON Schema Transformation Window

   

   
   

Once a JST has been added to a transition, the button to access the context menu of that transition changes into a diamond shape. The context menu itself contains several new options when a JST is present (Figure 14):

• Edit JST and Delete JST are used to edit or delete the JST attached to the transition, respectively.
• Insert Node Before JST and Insert Node After JST insert a new node into the workflow before or after the JST-enabled transition, respectively.

Figure 12: JST Transition Context Menu