12.2. Data Transformation Tutorial

Prerequisites

JBoss Fuse tooling installed on JBoss Developer Studio. See Install Red Hat JBoss Developer Studio Integration Stack
Maven installed and configured correctly. See Red Hat JBoss Fuse Maven Repositories
the transformation quickstart applications downloaded and installed

Importing the `starter` quickstart application

Right-click in Project Explorer to open the context menu.
Select Import Import....
Expand the Maven folder, and select Existing Maven Projects.
Click Next to open the Maven Projects wizard.
Click Browse to find and select the root directory of the starter quickstart application.
If the browse operation finds multiple projects, make sure you select the starter quickstart application. The full path to the starter quickstart application appears in the Projects pane.
Click Finish.
After the import operation finishes, the starter project appears in Project Explorer.
In Project Explorer, expand the starter project.
Double-click starter/src/main/resources/META-INF/spring/camel-context.xml to open it in the route editor.
Click the Source tab to view the underlying XML.
You can see that an XML file is produced from a source endpoint and a JSON file is consumed by a target endpoint.
Click the Design tab to return to Design view.
Remove the arrow connecting the source and target endpoints.
Note
Do not save your project now. If you do, the endpoints will disappear because they are not connected, which makes the route invalid.
If Console view is not already open, open it now by clicking Window Show View Console.

Note

Although the following mini tutorials are written to be run in consecutive order, you can run through them in any order, but the Console output per tutorial will differ from that shown.

Adding a data transformation node to the Camel route

In the Palette, expand the Transformation drawer.
Drag a Data Transformation component onto the canvas.
The New Transformation wizard opens with the Project, Dozer File Path, and Camel File Path fields auto filled.
Fill in the remaining fields:
- In Transformation ID, enter xml2json.
- For Source Type, select XML from the drop-down menu.
- For Target Type, select JSON from the drop-down menu.
Click Next.
The Source Type (XML) definition page opens, where you specify either an XML Schema (default) or an example XML Instance Document to provide the type definition of the source data:
Leave XML Schema enabled.
For Source file, browse to the location of the XML schema file or the XML instance file to use for the type definition of the source data, and select it (in this case, abc-order.xsd).
The XML Structure Preview pane displays a preview of the XML structure.
In Element root, enter ABCOrder.
The tooling uses this text to label the pane that displays the Source data items to map.
The Source Type (XML) definition page should now look like this:
Click Next.
The Target Type (JSON) definition page opens, where you specify the type definition for the target data.
Click JSON Instance Document.
In the Target File field, enter the path to the xyz-order.json instance document, or browse to it. The JSON Structure Preview pane displays a preview of the JSON data structure:
Click Finish.

The Transformation editor opens, so you can map data items in your XML source to data items in your JSON target.

The Transformation editor is composed of three panels:

Source—lists the available data items of the source
Transformations—displays the mappings between the source and target data items
Target—lists the available data items of the target

In addition, the editor's Details view, located just below the editor's three panels (once the first mapping has been made), graphically displays the hierarchical ancestors for both the mapped source and target data items currently selected. For example:

Details view with source property customerNum mapped to target property role="italic">custId

Using Details view, you can customize the mapping for the selected source and target data items:

Set property—Modify an existing mapping or map a simple data item to one in a collection (see the section called “Mapping a simple data item to a data item in a collection”)
Set variable—Specify a constant value for a data item (see the section called “Mapping a constant variable to a data item”)
Set expression—Map a data item to the dynamic evaluation of a specified expression (see the section called “Mapping an expression to a data item”)
Add function—Modify the value of a mapped data item using a built-in function (see the section called “Adding a built-in function to a mapped data item”)
Add custom function—Modify the value of a mapped data item using Java method you create or one you previously created (see the section called “Adding a custom function to a mapped data item”)

Mapping source data items to target data items

Expand all items in the Source and Target panels located on left and right sides of the Transformations panel.
Drag a data item from the Source panel and drop it on its corresponding data item in the Target panel.
For example, drag the customerNum data item from the Source panel and drop it on the custId data item in the Target panel.
The mapping appears in the Transformations panel, and the details of both the Source and Target data items appear below in Details view.
Continue dragging and dropping source data items onto their corresponding target data items until you have completed all basic mappings.
In the starter example, the remaining data items to map are:
Source Target
orderNum orderId
status priority
id itemId
price cost
quantity amount
Note
You can map collections (data items containing lists or sets) to noncollection data items and vice versa, but you cannot map collections to other collections.
Note
To easily discover which data items are collections, click in both the Source and Target panels. (Brackets appear before the name of any data item that is part of a collection.) For an example, see Step 1 in the section called “Adding a custom function to a mapped data item”.
Click on both the Source and Target panels to quickly determine whether all data items have been mapped.
Only data items that have not been mapped are listed in the Source and Target panels.
In the starter example, the remaining unmapped Target attributes are approvalCode and origin.
Click the camel-context.xml tab to return to the route editor in Design view.
Hover your cursor over each endpoint to reveal its connecter arrow.
Selecting the file:src/data?fil... node, drag and drop its connector arrow onto the ref:xml2json node. Likewise drag and drop the connector arrow from the ref:xml2json node onto the file:target/messa... node.
Connecting the nodes on the canvas creates a valid Camel route, which you can now save.
Click File Save.

Source	Target
`orderNum`	`orderId`
`status`	`priority`
`id`	`itemId`
`price`	`cost`
`quantity`	`amount`

You can run a JUnit test on your transformation file after you create the transformation test. For details, see the section called “Creating the transformation test file and running the JUnit test”. If you do so at this point, you will see this output in Console view:

<?xml version="1.0" encoding="UTF-8"?>
<ABCOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:java="http://java.sun.com">
    <header>
        <status>GOLD</status>
        <customer-num>ACME-123</customer-num>
        <order-num>ORDER1</order-num>
    </header>
    <order-items>
        <item id="PICKLE">
            <price>2.25</price>
            <quantity>1000</quantity>
        </item>
        <item id="BANANA">
            <price>1.25</price>
            <quantity>400</quantity>
        </item>
    </order-items>
</ABCOrder>

for the source XML data, and

{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","lineItems":[{"itemId":"PICKLE",
"amount":1000,"cost":2.25},{"itemId":"BANANA","amount":400,"cost":1.25

for the target JSON data.

Creating the transformation test file and running the JUnit test

Right-click the starter project in Project Explorer, and select New Other Fuse Tooling Fuse Transformation Test.
Select Next to open the New Transformation Test wizard.
In the New Transformation Test wizard, set the following values:
Field Value
Package example
Transformation ID xml2json
Click Finish.
In Project Explorer, navigate to starter/src/test/java/example, and open the TransformationTest.java file.

Field	Value
Package	`example`
Transformation ID	`xml2json`

Add the following code to the transform method:

startEndpoint.sendBodyAndHeader(readFile("src/data/abc-order.xml"), "approvalID", "AUTO_OK");

Click File Save.
You can now run a JUnit test on your transformation file at any point in these tutorials.
In Project Explorer, expand the starter project to expose the /src/test/java/example/TransformationTest.java file.
Right click it to open the context menu, and select Run as JUnit Test.
The JUnit Test pane opens to display the status of the test. To avoid cluttering your workspace, drag and drop the pane in the bottom panel near Console view.
Open Console view to see the log output.

Mapping a constant variable to a data item

When a source/target data item has no corresponding target/source data item, you can map a constant variable to the existing data item.

In the starter example, the target data item origin does not have a corresponding source data item. To map the origin attribute to a constant variable:

In the Source panel, click the Variables tab to open Variables view.
In Variables view, click to open the Enter a new variable name dialog.
Enter a name for the variable you want to create.
For the starter example, enter ORIGIN.
Click OK.
The newly created variable ORIGIN appears in Variables view in the Name column and the default value "ORIGIN" in the Value column.
Click the default value to edit it, and change the value to Web.
Press Enter.
Drag and drop the new variable ORIGIN onto the origin data item in the Target panel.
The new mapping of the variable $(ORIGIN) appears in the Transformations panel and in Details view.
Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.
Console view displays the json-formatted output data:
```
{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}
```

Mapping an expression to a data item

This feature enables you, for example, to map a target data item to the dynamic evaluation of a Camel language expression.

Use the target approvalCode data item, which lacks a corresponding source data item:

Click to add an empty transformation map to the Transformations panel.
From the Target panel, drag and drop the approvalCode data item to the target field of the newly created mapping in the Transformations panel.
The approvalCode data item also appears in Details view's target box.
In Details view, click on the ABCOrder source box to open the drop-down menu.
Menu options depend on the selected data item's data type. The available options are bolded.
Select Set expression to open the Expression dialog.
In Language, select the expression language to use from the list of those available. Available options depend on the data item's data type.
For the starter example, select Header.
In the Details pane, select the source of the expression to use.
The options are Value and Script.
For the starter example, click Value, and then enter ApprovalID.
Click OK.
Both Transformations panel and Details view display the new mapping for the target data item approvalCode.
Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.
Console view displays the json-formatted output data:
```
{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}
```

Adding a custom function to a mapped data item

You may need to modify the formatting of source data items when they do not satisfy the requirements of the target system.

For example, to satisfy the target system's requirement that all customer ids be enclosed in brackets:

Transformations panel, select the customerNum mapping to populate Details view.
In Details view, click on the ABCOrder source box to open the drop-down menu.
Select Add custom function to open the Add Custom Function page.
Click next to the Class field to open the Create New Java Class wizard.
Modify the following fields:
- Package—Enter example.
- Name—Enter MyCustomMapper.
- Method Name—Change map to brackets.
Leave all other fields as is.
Click Finish.
The Add Custom Function page opens with the Class and Method fields auto filled:
Click OK to open the MyCustomMapper.java file in the Java editor:
Edit the brackets method to change the last line return null; to this:
```
return "[" + input + "]";
```
Click the transformation.xml tab to switch back to the Transformation editor.
Details view shows that the brackets method has been associated with the customerNum data item.
The brackets method is executed on the source input before it is sent to the target system.
Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.
Console view displays the json-formatted output data:
```
{"custId":"[ACME-123]","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}
```

Mapping a simple data item to a data item in a collection

In this tutorial, you will modify an existing mapping that maps all ids in the Source to the itemIds in the Target. The new mapping will map the customerNum data item in the Source to the itemId of the second item in the lineItems collection in the Target.

With this change, no ids in the Source will be mapped to itemIds in the Target.

Note

To discover which data items are in collections, click Show data types icon

at the top of both the Source and Target panels. The data type of each item is displayed next to it.

In the Transformations panel, select the mapping id —> itemId to display the mapping in Details view.
On the Source box, click to open the drop-down menu, and select Set property.
In the Select a property page, expand the header node and select customerNum.
Click OK to save the change and open the Collection Indexes page.
In the Collection Indexes page, click the toggle button next to lineItems to increase its value to 1.
Indexes are zero-based, so a value of 1 selects the second instance of itemId in the collection.
Click OK to save the change and open the transformation.xml file.
Notice that Details view shows customerNum mapped to the itemId of the second item in the lineItems collection.
Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.
Console view displays the json-formatted output data:
```
{"custId":"[ACME-123]","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"amount":1000,"cost":2.25},
{"itemId":"ACME-123","amount":400,"cost":1.25}]}
```

Adding a built-in function to a mapped data item

You can use the built-in string-related functions to apply transformations to mapped data items.

In the Transformations panel, select the status to priority mapping to populate Details view.
In the Source box, click to open the drop-down menu, and select Add function.
In the Functions pane, select append, and in the Arguments pane, enter -level for the value of suffix.
This append function adds the specified suffix to the end of the status string before mapping it to the target priority data item.
Click OK.
By default, Details view displays the results of adding the append function to the status data item in a user-friendly format. You can change this formatting by clicking the right-most on the Source box, and selecting Show standard formatting.
Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.
Console view displays the json-formatted output data:
```
{"custId":"[ACME-123]","priority":"GOLD-level","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"amount":1000,"cost":2.25},{"itemId":"ACME-123",
"amount":400,"cost":1.25}]}
```

此内容没有您所选择的语言版本。

Prerequisites

Importing the `starter` quickstart application

Adding a data transformation node to the Camel route

Mapping source data items to target data items

Creating the transformation test file and running the JUnit test

Mapping a constant variable to a data item

Mapping an expression to a data item

Adding a custom function to a mapped data item

Mapping a simple data item to a data item in a collection

Adding a built-in function to a mapped data item

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Red Hat legal and privacy links

Red Hat legal and privacy links

此内容没有您所选择的语言版本。

12.2. Data Transformation Tutorial

Prerequisites

Importing the starter quickstart application

Adding a data transformation node to the Camel route

Mapping source data items to target data items

Creating the transformation test file and running the JUnit test

Mapping a constant variable to a data item

Mapping an expression to a data item

Adding a custom function to a mapped data item

Mapping a simple data item to a data item in a collection

Adding a built-in function to a mapped data item

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Red Hat legal and privacy links

Red Hat legal and privacy links

Importing the `starter` quickstart application