JST Designer

Itential Automation Platform (IAP) uses JavaScript Object Notation (JSON) to transfer serialized data. These data transfers can happen within a single IAP application, between IAP applications, or between IAP and external applications. IAP may need to transfer JSON data between endpoints that have different data formatting requirements. In these cases, IAP can use JSON Schema Transformations (JSTs) to allow the endpoints to communicate.

A JSON Schema Transformation (JST) uses a combination of JSON Schema and JavaScript methods to reformat JSON data, and can be created in IAP using the JST Designer application.

This page documents the features of JST Designer and provides guidance on the construction and use of JSON Schema Transformations (JSTs).

Creating a New JST

To create a new JST from the Automation Studio Quick Start page:

1. Click the Create (+) button from the toolbar located at the top of the side navigation menu; the Create modal will appear.
2. Select Transformation from the dropdown menu.
3. Enter a name and, optionally, a description for the JST.
4. Click the Create button; the new JST will be opened in JST Designer.

Figure 1: Create a New JST

Figure 2: Create Modal

Opening an Existing JST

To open an existing JST from the Automation Studio Quick Start page:

1. Click the down arrow for the Transformations collection from the side navigation menu; existing transformations will be listed in an accordion view.
2. Select the desired transformation to open it in JST Designer.

Figure 3: Open Existing Transformations

JST Designer Canvas

After you have created a new JST or selected an existing JST from the Automation Studio Quick Start page, it will be opened in the JST Designer canvas. The canvas is the main interface for constructing a JST, such as:

• Adding incoming or outgoing schemas to a JST.
• Adding methods to a JST.
• Creating functions and adding them to a JST.

Canvas UI

The main elements of the JST Designer canvas UI (Figure 4) are described below:

Figure 4: JST Designer Canvas UI

Incoming Schemas

When a JST receives JSON data to transform, the data is first validated against one or more incoming schemas. An incoming schema is a JSON schema that is used to ensure that any data structures or constraints required for the JST's input are met.

Incoming schemas can be added to a JST in two ways:

• Adding an incoming schema.
• Adding a workflow task schema, which is an incoming schema tailored to be used in conjunction with a specific workflow task.

Adding an Incoming Schema

Incoming schemas are created using the Add Incoming Schema modal.

To open the Add Incoming Schema modal from the JST Designer canvas, hover over the Add (+) button on the Incoming Schemas panel and select Incoming Schema from the context menu that appears.

The main elements of the Add Incoming Schema modal (Figure 5) are described below.

Figure 5: Add Incoming Schema Modal

Example - Creating Incoming Schemas

To create an incoming schema using the Add Incoming Schema modal:

1. Enter an incoming schema into the Schema Editor. This can be done in one of three ways:

   • Type or paste an incoming schema into the Schema Editor.
   • Type or paste an example of the JSON data that the JST should accept into the Example JSON Editor, then select the Infer Schema From Example JSON button.
   • Select the Upload Schema (↑) button to add an existing schema to the JST.

2. Provide a name for the incoming schema by editing the value of its $id key. If the $id key does not already exist in the incoming schema, add it as shown in Figure 6.

3. If the syntax of the incoming schema is correct, the Save button will become enabled; click it to add the incoming schema to the JST.

Figure 6: Creating an Incoming Schema

Adding a Workflow Task Schema

To add a workflow task schema to the JST from the JST Designer canvas:

1. Hover over the Add (+) button on the Incoming Schemas panel and select Workflow Task Schema from the context menu that appears; the Add Workflow Task Schema modal will open.
2. Select the relevant workflow task from the right-hand side of the modal. If you know the name of the task, you can search for it using the search bar at the top-right corner of the modal.
3. Confirm the details displayed for the selected task on the left-hand side of the modal, then click the Add button at the bottom-left corner of the modal.

Figure 7: Add Workflow Task Schema Modal

Editing, Copying, and Deleting an Incoming Schema

To edit, copy, or delete an existing incoming schema from the JST Designer canvas, hover over the incoming schema on the Incoming Schemas panel and select the relevant button (Figure 8) from the schema toolbar that appears.

Figure 8: Edit, Copy, or Delete Incoming Schema

Outgoing Schemas

Like an incoming schema defines the structure that data entering the JST must conform to, an outgoing schema is a JSON schema that is used to define the structure of the data leaving the JST. Data that the JST is operating on must be connected to an outgoing schema if it is to be part of the JST's output.

Connecting to an Outgoing Schema

To connect an incoming schema to an outgoing schema from the JST Designer canvas:

1. Select the desired schema or schema property from the Incoming Schemas panel by selecting its right-facing connector; this will initiate edge mode.
2. While in edge mode, hover over the Add (+) button of the Outgoing Schemas panel, then select Outgoing Schema from the context menu that appears. An appropriate outgoing schema will be generated and connected to the selected schema or schema property in the Incoming Schemas panel.
   • Alternatively, if an appropriate outgoing schema or schema property already exists, you can directly connect the incoming schema or schema property to it.

Example - Connecting Schemas

The example shown in Figure 9 extracts one property, vendor, from the switch incoming schema and connects it to the vendor outgoing schema. The JSON data output by this JST will only contain what was connected to the vendor outgoing schema; the rest of the input data will be discarded.

Figure 9: Incoming and Outgoing Schemas Connected

Methods

Incoming JST data data can be transformed before being connected to an outgoing schema through the use of methods. A method is a low-code, drag-and-drop representation of a JavaScript method on the JST Designer canvas.

Using a Method

To place a method on the JST Designer canvas:

1. Locate the desired method from the Methods tab of the work bench.
2. Drag the method to the canvas.
   • Method input parameters are listed on the left-hand side of the method while method return parameters are listed on the right-hand side.
   • Hover over the Information (ⓘ) icon in the header of the method to read more information about the method. Alternatively, select the icon to be redirected to the JavaScript documentation for the method.

To connect an incoming schema or schema property to the method:

1. Select the schema or schema property that you would like to transform from the Incoming Schemas panel by selecting its right-facing connector; this will initiate edge mode.
2. While in edge mode, select the left-facing connector of the appropriate method input parameter.

The return parameter for a method can be connected to the left-facing connector of another method, a function, or an outgoing schema.

Example - Connecting a Method

The example shown in Figure 10 connects several properties from the shippingAddress incoming schema to input parameters of the templateLiteral method. The templateLiteral method combines its input parameters into one return parameter. The return parameter is then connected to the address outgoing schema.

Figure 10: Method on the JST Designer Canvas

Constant Values (Formerly Known As thisArg)

Higher-order methods in JST Designer contain an optional parameter called constantValueN. These methods iterate through an array and accept a callback function as a parameter which is invoked on each iteration. The constantValueN parameter allows you to pass in any external data that you might need within this callback function.

Figure 11: IAP/2023.2 constantValueN

Example - Using Constant Values

In this example transformation, the employees array is passed to the map method to process. The purpose of this JST is to take this array and the provided company string and output an array of company emails. This logic is handled within the map callback function, and because the company name is not available in the array parameter, it is passed in as a constant value to the function.

Figure 12: JST Example

Within the callback function, you will find this argument in the Incoming Schemas panel. Each constant value you pass in to a higher-order method is displayed as an additional incoming schema. From here, you can make assignments from the constant value to utilize the data within the function.

Figure 13: Incoming Schemas Callback Function

Users can also edit constant values via the Incoming Schemas panel. To edit a constant value, you can follow the same steps from the Editing, Copying, and Deleting an Incoming Schema section above. Once updated, any higher-order methods that utilize this constant value will be updated dynamically.

Figure 14: Editing Constant Values

Figure 15: Constant Value Dyamic Update

Functions

A JST can also transform input data by using functions. A function is a child JST that is placed on the JST Designer canvas in a manner similar to methods. Using functions can allow for a more modular approach when building JSTs. For example, if an identical series of methods is used by many JSTs, a function can be created to perform the desired data transformation in one step.

Creating a Function

To create a function from the JST Designer canvas:

1. Select the Functions tab of the work bench.
2. Click the Add button on the functions toolbar; a blank JST Designer canvas will be opened in a new tab. Alternatively, select the Upload button on the functions toolbar to use a pre-existing exported JST as a function.

Figure 16: Functions Toolbar

3. Construct an appropriate JST; the JST will appear on the Functions tab of the work bench.
4. Drag the function to the canvas.
5. Connect the function to incoming schemas, outgoing schemas, methods, and other functions as you would with a method.

Example - Using a Function

The example depicted below connects the vendor and model properties from the switch incoming schema to the corresponding input parameters of the concatVendorAndModel function. The concatVendorAndModel function contains logic used to combine two string input parameters into a single string. Its input and return parameters are defined in the incoming and outgoing schemas of the function, respectively. The function's vendorAndModel return parameter is then connected to the venderAndModel outgoing schema.

Figure 17: Function on the JST Designer Canvas

Editing, Downloading, and Deleting Functions

To edit, download, or delete an existing function from the Functions tab of the JST Designer work bench:

1. Hover over the function in the work bench; this will display the function's edit, download, and delete buttons.
2. Select the relevant button.

Figure 18: Edit, Download or Delete Function

Running a JST

Once a JST has been constructed, you can use JST Designer to test the JST by running it with example JSON input. You can then examine the resulting JSON output to ensure that the JST is working as intended.

To run a JST from the JST Designer canvas:

1. Click the Run button from the toolbar; the Run Transformation modal appears.

2. Enter the JSON input that will be provided to the incoming schema.

3. Select the checkbox for any desired transformation options. These options are referenced below.

   Transformation Option	Function
   Validate Incoming	Ensures input is compatible with the incoming schema.
   Extract Output	Removes the output from its wrapper object if only a single outgoing schema property exists.
   Revert to Default Value	Enables the use of the default keyword in schemas.

   
   

4. Click the Run button at the bottom-left corner of the Run Transformation modal; the JST output will be displayed in the Log Console.

Editing JST Metadata

A JST has several metadata values, such as:

• The JST name.
• A description of the JST.
• Tags that have been assigned to the JST.

To view and edit the metadata values of a JST from the JST Designer canvas:

1. Click the menu button at the upper-right corner of the canvas; a menu will appear.
2. Select View metadata from the menu; a slider panel displaying the JST's metadata will appear from the top of the window.
3. Enter any desired metadata changes into the appropriate text input field.
4. Click the Save button at the bottom-left corner of the slider panel.

Figure 19: JST Metadata

Cloning, Exporting, and Deleting JSTs

To clone, export, or delete a JST from the JST Designer canvas:

1. Click the menu button at the upper-right corner of the canvas; a menu will appear.
2. Select Clone transformation, Export transformation, or Delete transformation from the menu, respectively (refer to UI Label 4 in Figure 4).

Further Reading

The following resources provide further insight into the use of JavaScript and JSON Schemas, including a pre-built collection of transformations that can be downloaded:

• JSON Website
• JSON Schema Website
• JavaScript Reference
• Itential Pre-Built Library