Create and manage transformations

A JSON Schema Transformation (JST) uses a combination of JSON Schema and JavaScript methods to reformat JSON data. JSTs are created and managed in Itential Platform using the JST Designer application.

Create a new JST

Select Transformation

Select Transformation from the dropdown menu.

Name the JST

Enter a name and, optionally, a description.

Create

Click Create. The new JST opens in JST Designer.

Open an existing JST

Click the down arrow for the Transformations collection in the side navigation to expand the list of existing transformations, then click the desired transformation to open it in JST Designer.

If you know the name of the JST you’re looking for, search for it using the Search Bar at the top of the Transformations accordion, or via the Studio Collection View.

JST Designer canvas

After you create or open a JST, it opens in the JST Designer canvas — the main interface for constructing a JST, including adding incoming and outgoing schemas, methods, and functions.

Canvas UI

Label	UI element	Function
1	Pre-built JST Dropdown	Lists pre-built JSTs that can be opened in a new tab.
2	Toggle Switch	Switches the canvas between dark mode and light mode.
3	Help Button	Launches an interactive tour of the canvas UI.
4	Menu Button	View/edit JST metadata, clone, export, or delete the JST.
5	JST Toolbar	Save, comment, copy to clipboard, run, and live preview.
6	Canvas Controls	Undo, redo, zoom out, and zoom in.
7	Incoming Schemas Panel	Displays incoming schemas; allows adding and editing.
8	Outgoing Schemas Panel	Displays outgoing schemas; allows adding and editing.
9	Work Bench	Searchable menu of methods and functions.
10	Console Drawer	Output and logging information generated during runtime.

Incoming schemas

When a JST receives JSON data, it is first validated against one or more incoming schemas — JSON schemas that ensure the input data meets the required structures and constraints.

Incoming schemas can be added in two ways: by adding a standard incoming schema, or by adding a workflow task schema (an incoming schema tailored to a specific workflow task).

Add an incoming schema

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

Label	UI element	Function
1	Upload Schema (↑)	Uploads an existing JSON schema.
2	Infer Schema From Example JSON	Generates an incoming schema from example JSON in the editor.
3	Infer JSON From Schema	Generates example JSON from the incoming schema.
4	Schema Editor	Edit the incoming schema directly.
5	Example JSON Editor	Enter example JSON from which a schema can be generated.

Create an incoming schema

Enter the schema

Enter an incoming schema into the Schema Editor using one of these methods: type or paste it directly; type or paste example JSON into the Example JSON Editor and click Infer Schema From Example JSON; or click Upload Schema (↑) to upload an existing schema file.

Name the schema

Provide a name by editing the value of the $id key. If the $id key doesn’t exist, add it to the schema.

Save

When the schema syntax is valid, the Save button becomes enabled. Click it to add the schema.

Add a workflow task schema

Select the task

Select the relevant workflow task from the right side of the modal. Use the search bar to find it by name.

Confirm and add

Review the task details on the left side, then click Add.

Edit, copy, or delete an incoming schema

Hover over an incoming schema in the Incoming Schemas panel. A toolbar appears with Edit, Copy, and Delete actions.

Outgoing schemas

An outgoing schema defines the structure of the data leaving the JST. Data being operated on must be connected to an outgoing schema to appear in the JST’s output.

Connect to an outgoing schema

Initiate edge mode

In the Incoming Schemas panel, click the right-facing connector on the schema or schema property you want to map.

Create or connect an outgoing schema

While in edge mode, hover over Add (+) on the Outgoing Schemas panel and select Outgoing Schema. An outgoing schema is generated and connected automatically. Alternatively, connect directly to an existing outgoing schema or property.

Outgoing schemas can also be created manually using the same steps as incoming schemas.

Methods

Incoming JST data can be transformed before connecting to an outgoing schema using methods — low-code, drag-and-drop representations of JavaScript methods on the canvas.

Use a method

Place the method

Locate the method in the Methods tab of the work bench and drag it to the canvas. Method input parameters are on the left; return parameters are on the right. Hover over the information icon (ℹ) in the method header for documentation.

Connect the input

In the Incoming Schemas panel, click the right-facing connector on the schema or property to transform. While in edge mode, click the left-facing connector of the appropriate method input parameter.

Connect the output

Connect the return parameter to another method, a function, or an outgoing schema.

Constant values

Higher-order methods in JST Designer contain an optional parameter called constantValueN. These methods iterate through an array and accept a callback function invoked on each iteration. The constantValueN parameter lets you pass external data into that callback function.

constantValueN parameter shown on a higher-order method in JST Designer

In early release versions (2022.1 and 2023.1), this parameter was called thisArg.

Example: use constant values

In this example, the employees array is passed to the map method. The JST takes this array and a provided company string and outputs an array of company emails. Because the company name is not available in the array parameter, it is passed in as a constant value to the callback function.

JST example using constantValueN to pass a company string into the map callback function

Within the callback function, the constant value appears in the Incoming Schemas panel as an additional incoming schema. Assignments can then be made from it within the function.

Incoming Schemas panel inside a callback function showing the constant value as an additional schema

To edit a constant value, hover over it in the Incoming Schemas panel and use the same controls described in Edit, copy, or delete an incoming schema. Higher-order methods using the constant value are updated dynamically.

Editing a constant value in the Incoming Schemas panel

Higher-order methods dynamically updated after editing the constant value

Functions

A JST can also transform data using functions — child JSTs placed on the canvas similarly to methods. Functions support a modular approach: if an identical series of methods is used by many JSTs, a function can encapsulate that logic in one reusable step.

Some methods require a function as an input parameter — these are called callback functions. Callback functions are embedded into the method itself rather than placed directly on the canvas. Hover over the information icon (ℹ) in the method header for details.

Create a function

Go to the Functions tab

Select the Functions tab of the work bench.

Add the function

Click Add to open a blank JST Designer canvas in a new tab. Alternatively, click Upload to use a pre-existing exported JST as a function.

Build the function

Construct the JST in the new tab. It appears in the Functions tab of the work bench once complete.

Use the function

Drag the function to the canvas and connect it to incoming schemas, outgoing schemas, methods, and other functions as you would with a method.

Edit, download, or delete a function

Hover over the function in the Functions tab of the work bench. Edit, download, and delete buttons appear. Click the relevant button.

Run a JST

Enter input data

Enter the JSON input to provide to the incoming schema.

Select options

Check any desired transformation options:

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.

Run

Click Run at the bottom left of the modal. The output appears in the Log Console.

Edit JST metadata

Select View metadata

Select View metadata. A slider panel opens from the top of the window.

Edit and save

Make changes in the appropriate fields and click Save.

Clone, export, or delete a JST

Click the menu button at the upper right of the canvas, then select Clone transformation, Export transformation, or Delete transformation.