- 15 Nov 2022
- Updated on 15 Nov 2022
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:
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
Select Transformation from the dropdown menu.
Enter a name and, optionally, a description for the JST.
Click the Create button; the new JST will be opened in JST Designer.
Figure 2: Create Modal
Opening an Existing JST
To open an existing JST from the Automation Studio Quick Start page:
- Click the down arrow for the Transformations collection from the side navigation menu; existing transformations will be listed in an accordion view.
- Select the desired transformation to open it in JST Designer.
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 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.
The main elements of the JST Designer canvas UI (Figure 4) are described below:
|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.
|Toggles the canvas theme between dark mode and light mode.
|Launches an interactive tour of the canvas UI.
|Allows a user to view and edit JST metadata, clone the JST, export the JST, or delete the JST.
|Displays icons used to perform JST management actions. From left to right, these are: Save, Comment, Copy to Clipboard, Run, and Live Preview.
|Displays icons used to perform canvas actions. From left to right, these are: Undo, Redo, Zoom Out, and Zoom In.
|Incoming Schemas Panel
|Displays incoming schemas and allows you to add or edit incoming schemas.
|Outgoing Schemas Panel
|Displays outgoing schemas and allows you to add or edit outgoing schemas.
|Displays a searchable menu of methods and functions that can be used in the JST.
|Displays output and logging information generated during JST runtime.
Figure 4: JST Designer Canvas UI
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.
|Upload Schema (↑)
|Uploads an existing JSON schema to the JST.
|Infer Schema From Example JSON
|Uses JSON data present in the Example JSON Editor to generate an incoming schema.
|Infer JSON From Schema
|Generates example JSON data based on the incoming schema.
|Allows you to edit the incoming schema.
|Example JSON Editor
|Allows you to enter example JSON data from which the incoming schema can be generated.
Figure 5: Add Incoming Schema Modal
To create an incoming schema using the Add Incoming Schema modal:
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.
Provide a name for the incoming schema by editing the value of its
$idkey. If the
$idkey does not already exist in the incoming schema, add it as shown in Figure 6.
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:
- 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.
- 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.
- 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.
|Edits the selected incoming schema.
|Copies the selected incoming schema.
|Deletes the selected incoming schema.
Figure 8: Edit, Copy, or Delete Incoming Schema
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:
- Select the desired schema or schema property from the Incoming Schemas panel by selecting its right-facing connector; this will initiate edge mode.
- 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.
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
Using a Method
To place a method on the JST Designer canvas:
- Locate the desired method from the Methods tab of the work bench.
- 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.
To connect an incoming schema or schema property to the method:
- 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.
- 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
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:
Select the Functions tab of the work bench.
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
Construct an appropriate JST; the JST will appear on the Functions tab of the work bench.
Drag the function to the canvas.
Connect the function to incoming schemas, outgoing schemas, methods, and other functions as you would with a method.
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
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
Editing, Downloading, and Deleting Functions
To edit, download, or delete an existing function from the Functions tab of the JST Designer work bench:
- Hover over the function in the work bench; this will display the function's edit, download, and delete buttons.
- Select the relevant button.
Figure 13: 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:
Click the Run button from the toolbar; the Run Transformation modal appears.
Enter the JSON input that will be provided to the incoming schema.
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.
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:
- Click the menu button at the upper-right corner of the canvas; a menu will appear.
- Select View metadata from the menu; a slider panel displaying the JST's metadata will appear from the top of the window.
- Enter any desired metadata changes into the appropriate text input field.
- Click the Save button at the bottom-left corner of the slider panel.
Figure 14: JST Metadata
Cloning, Exporting, and Deleting JSTs
To clone, export, or delete a JST from the JST Designer canvas:
- Click the menu button at the upper-right corner of the canvas; a menu will appear.
- Select Clone transformation, Export transformation, or Delete transformation from the menu, respectively (refer to UI Label 4 in Figure 4).
Pre-built transformations are also available directly from the JST Designer canvas via the Pre-built JST dropdown menu.