Chapter 9. Getting Started with Data Transformation

9.1. Creating a project for the data transformation example
Copiar enlace

Create a new Fuse Integration Project (select File New Fuse Integration Project).
Provide the following information in the wizard:
- Project name: starter
- Deployment platform: Standalone
- Runtime environment: Karaf/Fuse on Karaf
- Camel version: Use the default
- Template: Empty - Blueprint DSL
Download the prepared data examples from: https://github.com/FuseByExample/fuse-tooling-tutorials/archive/user-guide-11.1.zip
Extract the data folder and the three files that it contains from the user-guide-11.1.zip archive into the Fuse Integration project’s src directory (starter/src/data).
In the Project Explorer view, expand the starter project.
Double-click Camel Contexts src/main/resources/OSGI-INF/blueprint/blueprint.xml to open the route in the route editor’s Design tab.
Click the Source tab to view the underlying XML.

Replace <route id="_route1"/> with the following code:

<route id="_route1">
  <from id="_from1" uri="file:src/data?fileName=abc-order.xml&amp;noop=true"/>
  <setHeader headerName="approvalID" id="_setHeader1">
    <simple>AUTO_OK</simple>
  </setHeader>
  <to id="_to1" uri="file:target/messages?fileName=xyz-order.json"/>
</route>

<route id="_route1">
  <from id="_from1" uri="file:src/data?fileName=abc-order.xml&amp;noop=true"/>
  <setHeader headerName="approvalID" id="_setHeader1">
    <simple>AUTO_OK</simple>
  </setHeader>
  <to id="_to1" uri="file:target/messages?fileName=xyz-order.json"/>
</route>

Copy to Clipboard

Toggle word wrap

Click the Design tab to return to the graphical display of the route:

View larger image

9.2. Adding a data transformation node to the Camel route
Copiar enlace

In the Palette, expand the Transformation drawer.
Click the Data Transformation pattern and then, in the canvas, click the arrow between the SetHeader _setHeader1 and To_to1 nodes.
The New Transformation wizard opens with the Dozer File Path field auto-filled.

View larger image
Fill in the remaining fields:
- In the Transformation ID field, 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:

View larger image
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 the Element root field, 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:

View larger image
Click Next to open the Target Type (JSON) definition page. This is where you specify the type definition for the target data.

View larger image
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:

View larger image
Click Finish.

The transformation editor opens. This is where 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
Mappings — 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 pane, 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:

custId" id="uid--yen25u4lh" onclick="event.preventDefault()"> Details pane with source property customerNum mapped to target property role=

custId" class="doc-image" loading="lazy">

Using the details pane, 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 Section 9.8, “Mapping a simple data item to a data item in a collection”).
Set variable — Specify a constant value for a data item (see Section 9.5, “Mapping a constant variable to a data item”).
Set expression — Map a data item to the dynamic evaluation of a specified expression (see Section 9.6, “Mapping an expression to a data item”).
Add transformation — Modify the value of a mapped data item using a built-in function (see Section 9.9, “Adding a built-in function to a mapped data item”).
Add custom transformation — Modify the value of a mapped data item using the Java method you create or one you previously created (see Section 9.7, “Adding a custom transformation to a mapped data item”).

9.3. Mapping source data items to target data items
Copiar enlace

Expand all items in the Source and Target panels located on left and right sides of the Mappings panel.

View larger image
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.

View larger image

The mapping appears in the Mappings panel, and the details of both the Source and Target data items appear below in the details pane.

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:

Expand

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

Note

You can map collections (data items containing lists or sets) to non-collection data items and vice versa, but you cannot map collections to other collections.

Click on both the Source and Target panels to quickly determine whether all data items have been mapped.

View larger image

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 blueprint.xml tab to return to the graphical display of the route:

View larger image
Click File Save.

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

For the source XML data:

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

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

Copy to Clipboard

Toggle word wrap

For the target JSON data:

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

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

Copy to Clipboard

Toggle word wrap

9.4. Creating the transformation test file and running the JUnit test
Copiar enlace

Right-click the starter project in the Project Explorer view, 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:

Expand

Field	Value
Package	`example`
Camel File Path	`OSGI-INF/blueprint/blueprint.xml`
Transformation ID	`xml2json`

Click Finish.
In the Project Explorer view, navigate to starter/src/test/java/example, and open the TransformationTest.java file.

Add the following code to the transform method:

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

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

Copy to Clipboard

Toggle word wrap

Click File Save.
You can now run a JUnit test on your transformation file at any point in these tutorials.
In the Project Explorer view, 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 the Console view.

View larger image
Open the Console view to see the log output.

9.5. Mapping a constant variable to a data item
Copiar enlace

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

View larger image
In the Variables view, click to open the Enter a new variable name dialog.

View larger image
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 the 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.

View larger image

The new mapping of the variable $(ORIGIN) appears in the Mappings panel and in the details pane.

Run a JUnit test on your TransformationTest.java file. For details, see Section 9.4, “Creating the transformation test file and running the JUnit test”.

The 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}]}

{"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}]}

Copy to Clipboard

Toggle word wrap

9.6. Mapping an expression to a data item
Copiar enlace

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 Mappings panel.

View larger image
From the Target panel, drag and drop the approvalCode data item to the target field of the newly created mapping in the Mappings panel.

View larger image

The approvalCode data item also appears in the details pane’s target box.
In the details pane, click on the ABCOrder source box to open the drop-down menu.

View larger image

Menu options depend on the selected data item’s data type. The available options are bolded.
Select Set expression to open the Expression dialog.

View larger image
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.

View larger image

Both the Mappings panel and the details pane display the new mapping for the target data item approvalCode.

Run a JUnit test on your TransformationTest.java file. For details, see Section 9.4, “Creating the transformation test file and running the JUnit test”.

The 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}]}

{"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}]}

Copy to Clipboard

Toggle word wrap

9.7. Adding a custom transformation to a mapped data item
Copiar enlace

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:

In the Mappings panel, select the customerNum mapping to populate the details pane.

View larger image
In the details pane, click on the ABCOrder source box to open the drop-down menu.

View larger image
Select Add custom transformation to open the Add Custom Transformation page.

View larger image
Click next to the Class field to open the Create a New Java Class wizard.

View larger image
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 Transformation page opens with the Class and Method fields auto filled:

View larger image
Click OK to open the MyCustomMapper.java file in the Java editor:

View larger image
Edit the brackets method to change the last line return null; to this:
```
return "[" + input + "]";
```
```
return "[" + input + "]";
```
Copy to Clipboard Toggle word wrap
Click the transformation.xml tab to switch back to the transformation editor.

View larger image

The details pane 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 Section 9.4, “Creating the transformation test file and running the JUnit test”.

The 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}]}

{"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}]}

Copy to Clipboard

Toggle word wrap

9.8. Mapping a simple data item to a data item in a collection
Copiar enlace

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.

In the Mappings panel, select the mapping id — > itemId to display the mapping in the details pane.

View larger image
On the Source box, click to open the drop-down menu, and select Set property.

View larger image
In the Select a property page, expand the header node and select customerNum. Click OK to save the changes.

View larger image
The details pane now shows that XyzOrder has a lineItems field. Click the toggle button next to lineItems to increase its value to 1.
Note
Indexes are zero-based, so a value of 1 selects the second instance of itemId in the collection.

View larger image

Notice that the details pane 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 Section 9.4, “Creating the transformation test file and running the JUnit test”.

The 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}]}

{"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}]}

Copy to Clipboard

Toggle word wrap

9.9. Adding a built-in function to a mapped data item
Copiar enlace

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 the details pane.

View larger image
In the Source box, click to open the drop-down menu, and select Add transformation.

View larger image
In the Transformations 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.

View larger image
Click OK.

View larger image

By default, the details pane 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.

View larger image

Run a JUnit test on your TransformationTest.java file. For details, see Section 9.4, “Creating the transformation test file and running the JUnit test”.

The 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}]}

{"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}]}

Copy to Clipboard

Toggle word wrap

9.10. Publishing a Fuse Integration project with data transformation to a Red Hat Fuse server
Copiar enlace

Before you publish your data transformation project to a Fuse server (see Chapter 29, Publishing Fuse Integration Projects to a Server), you need to install the following features in the Fuse runtime:

camel-dozer
camel-jackson
camel-jaxb

To install the required features on the Fuse runtime:

If not already there, switch to the Fuse Integration perspective.
If necessary, add the Fuse server to the Servers list (see Section 28.1, “Adding a Server”).
Start the Fuse Server (see Section 28.2, “Starting a Server”), and wait for the JBoss Fuse shell to appear in the Terminal view.
For each of the required camel- features, at the JBossFuse:admin@root> prompt type:
features:install camel-<featureName>
Where featureName is one of dozer, jackson, or jaxb.
To verify that each of the features was successfully installed, at the JBossFuse:admin@root> prompt type:
features:list --ordered --installed
You should see the camel features you just installed in the output listing:

View larger image

Este contenido no está disponible en el idioma seleccionado.

9.1. Creating a project for the data transformation example
Copiar enlace

9.2. Adding a data transformation node to the Camel route
Copiar enlace

9.3. Mapping source data items to target data items
Copiar enlace

9.4. Creating the transformation test file and running the JUnit test
Copiar enlace

9.5. Mapping a constant variable to a data item
Copiar enlace

9.6. Mapping an expression to a data item
Copiar enlace

9.7. Adding a custom transformation to a mapped data item
Copiar enlace

9.8. Mapping a simple data item to a data item in a collection
Copiar enlace

9.9. Adding a built-in function to a mapped data item
Copiar enlace

9.10. Publishing a Fuse Integration project with data transformation to a Red Hat Fuse server
Copiar enlace

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Hacer que el código abierto sea más inclusivo

Acerca de Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Este contenido no está disponible en el idioma seleccionado.

Chapter 9. Getting Started with Data Transformation

9.1. Creating a project for the data transformation exampleCopiar enlaceEnlace copiado en el portapapeles!

9.2. Adding a data transformation node to the Camel routeCopiar enlaceEnlace copiado en el portapapeles!

9.3. Mapping source data items to target data itemsCopiar enlaceEnlace copiado en el portapapeles!

9.4. Creating the transformation test file and running the JUnit testCopiar enlaceEnlace copiado en el portapapeles!

9.5. Mapping a constant variable to a data itemCopiar enlaceEnlace copiado en el portapapeles!

9.6. Mapping an expression to a data itemCopiar enlaceEnlace copiado en el portapapeles!

9.7. Adding a custom transformation to a mapped data itemCopiar enlaceEnlace copiado en el portapapeles!

9.8. Mapping a simple data item to a data item in a collectionCopiar enlaceEnlace copiado en el portapapeles!

9.9. Adding a built-in function to a mapped data itemCopiar enlaceEnlace copiado en el portapapeles!

9.10. Publishing a Fuse Integration project with data transformation to a Red Hat Fuse serverCopiar enlaceEnlace copiado en el portapapeles!

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Hacer que el código abierto sea más inclusivo

Acerca de Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

9.1. Creating a project for the data transformation example
Copiar enlace

9.2. Adding a data transformation node to the Camel route
Copiar enlace

9.3. Mapping source data items to target data items
Copiar enlace

9.4. Creating the transformation test file and running the JUnit test
Copiar enlace

9.5. Mapping a constant variable to a data item
Copiar enlace

9.6. Mapping an expression to a data item
Copiar enlace

9.7. Adding a custom transformation to a mapped data item
Copiar enlace

9.8. Mapping a simple data item to a data item in a collection
Copiar enlace

9.9. Adding a built-in function to a mapped data item
Copiar enlace

9.10. Publishing a Fuse Integration project with data transformation to a Red Hat Fuse server
Copiar enlace