A JSON Schema Transformation (JST) in simple terms is the transformation of data usually from a web-based application to a company’s internal database or vice versa. Transferred JSON data has to be reformatted in order to work with other applications not written in JSON or if the data is in a different non-JSON format.
The Itential Automation Platform (IAP) has a built-in JSON Schema Transformation Tool which allows you to leverage pre-built templates that are editable or you can create a new transformation. This guide will illustrate how to use both the pre-builts and how to build your own transformation utilizing the JST Tool.
Create a New JST
To access the transformation tool and create a new JST:
Go to IAP → Automation Studio → Transformations.
Figure 1: Transformations
From the Transformations collection menu, you can search for an existing JST or select one from the dropdown list.
To create a new JST, click the plus sign (+) in the circle located in the top toolbar above the menus.
Figure 2: Create New
The Create dialog will open. Select Transformation from the dropdown menu.
Figure 3: Select Transformation
Enter a name for your JST (this is a mandatory field) and a description (which is an optional field), and then click Create to save the new JST.
Figure 4: Create New JST
A blank canvas will open. This is where the new JST will be created. Click the plus sign (+) to add an incoming schema.
Figure 5: Blank JST Canvas
There are three (3) different ways to create a new JST:
- Cut and paste a schema into the left side window (editor).
- Paste the information in the right side window and click the Infer Schema From Example JSON link.
- Click the ↑ Schema upload button and navigate to the location of the JSON file you are going to use.
Figure 6: JSON Import Methods
For this example, the Infer Schema method was used to import the JSON.
- Paste the example JSON into the right side window and click the Infer Schema From Example JSON link.
- If the code is correct the Save button will become enabled and appear blue.
- Click Save and the JSON will appear on the Transformation canvas.
Figure 7: Infer Schema
The inferred JSON created in the previous step is displayed under the Incoming Schemas column.
Figure 8: Incoming Schemas Column
Now the rest of JST can be built using the methods and functions in the column on the right side.
Figure 9: Methods & Functions
You can test your Transformation by clicking the Run button on the left side of the canvas. Lastly, make sure to save all changes, this will allow you to use the Transformation again.
Figure 10: Run & Save
Using Pre-Built JST
To use a pre-built JST:
Select the type of pre-built you want to use from the pre-built dropdown on the right side.
Type Description Template Example Allows you to concatenate (i.e., bring one or more) strings together while using embedded expressions and improving readability. Map Example Creates a new array with the results of a function that are used on every member in the calling array. Find Example Will return the value of the first element in the array that satisfies the provided testing function. If there is no element that meets the testing function, undefined is returned. Query Example Allows you to set the parameters of what you are searching for. The query should return any and all elements that meet the search criteria.
Figure 11: Pre-built JSTs
Once you have selected a pre-built JST to use, click the Edit button above the incoming schema.
Figure 12: Edit Pre-built
Select the method for adding your data (i.e., cut/paste, infer, or upload) as referenced in the previous section.
Paste the JSON in the right side (white canvas) window and click the Infer Schema From Example JSON link.
Figure 13: Infer Schema
Click Save to continue.
Figure 14: Save JSON
Once the JSON data is in the pre-built JST template, create (draw) connections between the incoming and outgoing schemas. When you select a field from the Incoming Schema column, the corresponding Outgoing Schemas fields will show blue if it is a match or red if it is not a match.
Important: The field types need to match (i.e., object to object, integer to integer, etc.).
Figure 15: Match Fields
Click the Run button to test.
Figure 16: Run to Test
The Output tab at the bottom of the canvas will display the results.
Figure 17: Review Output