> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs-test.itntl.com/itential-platform/6/llms.txt
> - 2023.2: https://docs-test.itntl.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-test.itntl.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server.

# Create and manage transformations

> How to create, configure, and run JSON Schema Transformations (JSTs) in the Itential Platform JST Designer.

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

#### Open the Create modal

Click the **Create (+)** button from the toolbar at the top of the side navigation menu.

#### 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.

> **Info**
>
> 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.  |

![](/_fern-img/e3bc9e013e01d4022e8715989d02d99ef3d5730f69b6552c000867dcf2e1bc0b.webp)

## 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

#### Open the modal

Hover over **Add (+)** on the Incoming Schemas panel and select **Workflow Task Schema**. The Add Workflow Task Schema modal opens.

#### 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.

> **Info**
>
> 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.

![](/_fern-img/6bd4e3173bc57fb92896407bb93d9fd305927a3b0dbd2242d08f2b0a71fe2265.webp)

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

![](/_fern-img/d47335ead744e0106232aa37ee4e88d090ef38989fe20a94e98ace86749a048c.webp)

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.

![](/_fern-img/28b8e1a96a3e7d214a524010e824b755cb73c3a3f7ec7a0119ea3f904d39ebaa.webp)

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](#edit-copy-or-delete-an-incoming-schema). Higher-order methods using the constant value are updated dynamically.

![](/_fern-img/5fe9de3153433919cdbc735ce2a4c486df4b1788f120b0bbebe124b72426eb48.webp)![](/_fern-img/56368f86373f10c7697be09e30f3226ceebf6d14e95d8fb8965cc2f2d3fea1ed.webp)

## 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.

> **Note**
>
> 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

#### Open the Run Transformation modal

Click the **Run** button in the JST toolbar.

#### 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

#### Open the menu

Click the **menu** button at the upper right of the canvas.

#### Select edit details

Select **Edit Details**. 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**.

## Further reading

* [JSON](https://www.json.org/json-en.html)
* [JSON Schema](https://json-schema.org/)
* [JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference)
* [Itential Pre-Built Library](https://www.itential.com/pre-built-collection/?_sft_prebuilt_type=transformation)

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