Red Hat SummitChapter 5. Kaoto DataMapper
Currently Kaoto DataMapper is only supported inside the Visual Studio Code extension as a technical preview feature. In the future we will aim to bring this functionality also to the pure web version of Kaoto.
The DataMapper supports both XML and JSON schema for rendering the data structure. For both XML and JSON data, it internally generates a single XSLT step to perform configured data mappings at runtime. For JSON data, it leverages the json-to-xml() and xml-to-json() functions available in XSLT 3.0 to handle JSON transformations. While you can consume multiple XML/JSON documents using Camel Variables and/or Message Headers which are mapped to transformation parameters, the output is only a Camel Message Body.
In addition to the regular Camel steps, Kaoto supports a Kaoto DataMapper step to be placed in the Camel Route. The Kaoto DataMapper step provides a graphical user interface to create data mappings inside the Camel Route.
5.1. Adding a DataMapper step
Add a Kaoto DataMapper step in your Camel route. When you
Append,Prepend, orReplacea step in the Kaoto Design view, you can find the Kaoto DataMapper step in the catalog.
Click the added Kaoto DataMapper step in the Kaoto Design to open the config form.
In the Kaoto DataMapper config form, click the
Configurebutton.This will open the visual DataMapper editor.
5.2. Source and Target
In the DataMapper editor, you can see Source at the left and Target section at the right side.
The Source section represents the input side of your mappings, where the DataMapper step reads the data from. This is mapped to the incoming Camel Message as well as possible Camel Variables.
The Target section represents the output side of your mappings, where the DataMapper step writes the data to. This is mapped to the outgoing Camel Message.
5.3. Parameters
The Parameters section inside the Source is mapped to any of incoming Camel Variables and Message Headers. For example, if there is an incoming Camel Variable orderSequence, you can consume it by adding a Parameter orderSequence in the DataMapper Source/Parameters section.
Follow the below steps to add a parameter:
Click the plus (+) button on the right side of the
Parameterstitle.Now type the parameter name and click the check button on the right.
While Camel Exchange Properties are also mapped to Parameters in current camel-xslt-saxon implementation, after the Camel Variables has been introduced, it is no longer recommended to store application data into Camel Exchange Properties. We encourage to use Camel Variables instead.
5.4. Attaching Document schema files
If any of Source Body, Target Body and/or Parameter(s) are structured data, you can attach a schema file and visualize the data structure in a tree style view. The DataMapper supports both XML Schema (XSD) and JSON Schema files.
If the data is not structured and just a primitive value, you don’t need to attach a schema file.
JSON schemas can be attached to Target Body and Parameter(s). However, it is currently not supported to attach JSON schema to Source Body.
Follow the below steps to attach a schema file:
- Place schema file(s) inside the workspace directory.
Click
Attach a schemabutton in one of theSource Body,Target BodyorParameterssections.
In the Attach schema modal, click the file button.
Select the schema file to attach.
New! (XML only) Select the root element. The first element in the schema is selected by default. If the XML schema defines multiple top level elements and you want to use the other element than the first one, select one from the dropdown. This step is applicable only for XML. For JSON, skip to the next.
Here is a demo screencast to choose a root element.
Click
Attachbutton.Now the document structure is rendered inside a tree.
5.5. JSON schema document
Kaoto DataMapper supports reading structured JSON parameter(s) and writing a JSON target body. If any of them is a structured JSON data and you have a JSON schema which defines the JSON data structure, you can attach the JSON schema file, render the document tree in DataMapper UI and create data mappings with it.
Follow the below steps to attach a JSON schema file.
- Place schema file(s) inside the workspace directory.
Click
Attach a schemabutton in one of theTarget BodyorParameterssections.In the Attach schema modal, click the file button.
Select the schema file to attach.
If the file extension is
.json, it automatically switch the radio button below toJSON Schema. Otherwise, chooseJSON Schema. ClickAttachbutton.Now the JSON schema document structure is rendered inside a tree.
Here is a demo screencast for creating JSON mappings.
5.5.1. JSON schema document tree
Kaoto DataMapper uses XSLT 3.0 json-to-xml() and xml-to-json() functions to support JSON mappings. JSON document specific characteristics described in this section are mostly influenced by these XSLT 3.0 JSON support functions. Please visit XSLT 3.0 specification for more internal details.
When an XML schema document is rendered in DataMapper document tree, their element name and attribute name alone is shown as the field label. For JSON schema document, it is slightly different. Since JSON document field sometimes doesn’t have a name (anonymous), it uses field type as a primary field label.
-
map: object field -
array: array field -
string: string field -
number: number field
In addition to that, if the field has a name, it will show as a @key attribute following the field type. For example, a string type field with a name AccountId will show the field label string [@key = AccountId].
An anonymous object field will show just map.
There is one thing that requires attention for array type field. The array type field indicates that its children are collection, in other words repeating field, but not the array type field itself. For example, array type field with the name Item is rendered in DataMapper UI as following:
In this case, the map type field which is a direct child of array type field Item, is a collection field. The layer icon:
indicates that the map field is a collection field. This is important when creating a for-each mapping. We will look into how to create a for-each mapping in details later in this manual.
Here is an example JSON data mappings created in Kaoto DataMapper UI. It consumes Account and Cart structured JSON parameters as well as orderSequence primitive parameter, and create a ShipOrder JSON target body.
You might notice that in the XPath expression, it uses $Account-x to refer the parameter Account, not just $Account, but with a suffix -x. Since Account parameter is a structured JSON, it is internally converted into XML with using json-to-xml. $Account-x is a variable which stores that XML document converted from JSON.
When data mappings are created through drag and drop, Kaoto DataMapper automatically handles that. However, when you edit the XPath expression manually, please keep this fact in mind.
With those JSON specific characteristics in mind, the rest of the way how to create mappings is same for XML and JSON. You can create mappings for XML to XML, XML to JSON, JSON to XML and JSON to JSON with Kaoto DataMapper. We will look into those in the following sections.
5.6. Creating simple mappings
5.6.1. Creating a mapping by dragging and dropping a field
When you perform drag and drop between the source and the target, a mapping is created and a line is drawn between the fields.
Example: Mapping the Name fields by dragging and dropping the source Name field on the target Name field.
Before:
After:
5.6.2. Creating a mapping by typing XPath expression
You can also create a mapping by entering a XPath expression.
Click the 3 dots context menu and selecton the target field and choose
Add selector expression.Then enter the
XPathexpression
5.7. Creating conditional mappings
The DataMapper supports creating 3 types of conditional mappings:
-
if- The mapping is created only when the specified condition is met. -
choose-when-otherwise- The mapping is created depending on how the condition is satisfied. If thewhenbranch condition is satisfied, thewhenbranch mapping is .created. If nowhenbranch condition is satisfied, then theotherwisebranch mapping is created. -
for-each- The mapping is created for each item in the collection. Collection means multiple occurrences, which is often represented as an array.
5.7.1. Creating an if mapping
Click the 3 dots context menu on the target section’s field. Then select
wrap with "if"to create a mapping.Configure the
ifcondition. You can drag the source field and drop it into the input field to build a condition, or alternatively type everything manually.Configure the mapping by using drag and drop or by typing it manually.
5.7.2. Creating a choose-when-otherwise mapping
Click the 3 dots context menu on the target section’s field. Then select
wrap with "choose-when-otherwise"to create a mapping.Configure the
whencondition.Configure the mapping for the
whenbranch.Configure the mapping for the
otherwisebranch.If required, you can add one or more
whenbranches. To add anotherwhenbranch you can click the 3 dots menu on thechoosefield in theTargetsection and then selectAdd "when".
5.7.3. Creating a for-each mapping
When a field is a collection field (means multiple occurrences, often represented as an array), you can create a for-each mapping. The layer icon on the field indicates that it is a collection field.
Click the 3 dots context menu on the target section’s collection field. Then select wrap with "for-each" to create a mapping.
Configure the for-each condition by specifying the source collection field to iterate over.
Configure the mappings below. Note that the mapping field path is now a relative path from the collection field specified in the for-each condition.
5.8. Using XPath expression editor
The XPath editor is still under initial development and it currently supports only limited drag and drop. In future releases, more syntax assisting features will be added.
If you want to write something more in XPath expression rather than just a field path, you can launch the XPath expression editor and work with it. There is a pencil icon on the target field which launches the XPath expression editor when you click it.
Click the pencil button on a target field which has a mapping.
This will open up the
XPatheditor.You can then type in the editor at the right or drag a
Fieldfrom the left and drop onto the editor.You can also drag and drop
XPathfunctions from theFunctiontab on the left side.Drag the function and drop it onto the editor.
Once it’s completed, click the
Closebutton at the bottom left.Now you can see the new mapping in the tree view.
5.9. Deleting a mapping
To delete a mapping you can click the dustbin button next to the target field.
You then have to confirm the deletion by clicking the
Confirmbutton.Mapping is deleted.
5.10. Deleting a parameter
To delete a parameter, click the dustbin button next to the parameter.
You then have to confirm the deletion by clicking the
Confirmbutton.The parameter is deleted.
5.11. Detaching a schema
Similar to attaching a schema you can also remove / detach a schema.
Click the
Detach schemabutton.Click the
Confirmbutton.Now the Document got back to be a primitive value.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}