JST Designer
  • 18 Oct 2024
  • Dark
    Light
  • PDF

JST Designer

  • Dark
    Light
  • PDF

Article summary

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.

    Figure 1: Create a New JST
    jst_create_22.2

  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 2: Create Modal
    jst_create_modal_22.2


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.
Note:

If you know the name of the desired JST, you can search for it directly by using the Search Bar located at the top of the Transformations accordion menu. Alternatively, you can search for it via the Automation Studio Collection View.

Figure 3: Open Existing Transformations
jst_transformationsCollection


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:

Label UI Element Function
1 Pre-built JST Dropdown Displays a list of pre-built JSON Schema Transformations that can be opened. Select a pre-built JST to open it in a new tab.
2 Toggle Switch Toggles the canvas theme between dark mode and light mode.
3 Help Button Launches an interactive tour of the canvas UI.
4 Menu Button Allows a user to view and edit JST metadata, clone the JST, export the JST, or delete the JST.
5 JST Toolbar Displays icons used to perform JST management actions. From left to right, these are: Save, Comment, Copy to Clipboard, Run, and Live Preview.
6 Canvas Controls Displays icons used to perform canvas actions. From left to right, these are: Undo, Redo, Zoom Out, and Zoom In.
7 Incoming Schemas Panel Displays incoming schemas and allows you to add or edit incoming schemas.
8 Outgoing Schemas Panel Displays outgoing schemas and allows you to add or edit outgoing schemas.
9 Work Bench Displays a searchable menu of methods and functions that can be used in the JST.
10 Console Drawer Displays output and logging information generated during JST runtime.


Figure 4: JST Designer Canvas UI
jst_canvas_22.2


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.

Label UI Element Function
1 Upload Schema (↑) Uploads an existing JSON schema to the JST.
2 Infer Schema From Example JSON Uses JSON data present in the Example JSON Editor to generate an incoming schema.
3 Infer JSON From Schema Generates example JSON data based on the incoming schema.
4 Schema Editor Allows you to edit the incoming schema.
5 Example JSON Editor Allows you to enter example JSON data from which the incoming schema can be generated.


Figure 5: Add Incoming Schema Modal
jst_add_incoming_schema_22.2


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
jst_add_incoming_schema_JSON_editor_22.2


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
jst_canvas_add_workflow_task_schema_22.2


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.

Label UI Element Function
1 Edit Edits the selected incoming schema.
2 Copy Copies the selected incoming schema.
3 Delete Deletes the selected incoming schema.


Figure 8: Edit, Copy, or Delete Incoming Schema
jst_canvas_edit_incoming_schema_22.2


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.
Note:

Outgoing schemas can also be created manually in the same manner as incoming schemas.

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
jst_canvas_connected_schemas_22.2


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
jst_canvas_method_22.2


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 (Figure 11); a blank JST Designer canvas will be opened in a new tab.

    • Alternatively, select the Upload button (Figure 11) on the functions toolbar to use a pre-existing exported JST as a function.

      Label UI Element Function
      1 Add Opens a blank JST Designer canvas in a new tab for creating a new function.
      2 Upload Uploads a pre-existing exported JST to be used as a function.
      3 Remove Unused Functions Deletes any functions not used by the JST.


      Figure 11: Functions Toolbar
      jst_canvas_functions_toolbar_22.2


  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.

Note:

Some methods require the use of a function as an input parameter in their operation. Functions used in this way are known as callback functions. Callback functions are not placed directly on the canvas; instead, they are embedded into the method itself. The purpose of a callback function varies depending on its associated method. Hover over the Information (ⓘ) icon in the header of the method in question for more information.

Example - Using a Function

The example shown in Figure 12 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 12: Function on the JST Designer Canvas
jst_canvas_function_22.2


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 13: Edit, Download or Delete Function
jst_edit_download_delete_funnction_21.2.png


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 14: JST Metadata
jst_canvas_metadata_22.2


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:

Note:

Pre-built transformations are also available directly from the JST Designer canvas via the Pre-built JST dropdown menu.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.