# Step 3: Mapping Elements and Attributes

In this step, you map source nodes to target nodes. The following figure shows the mapping of example XML data.

Figure : Mapping Example

In the preceding figure, the source XML data has a different format than the target XML data. When building a query invoked by a Transformation method, you map the source nodes to target nodes as represented by the arrows. During run time, the transformation uses the mappings to convert the data from the source format to the target format. For example, the arrow labeled 1 represents the transformation of the priceQuote/customerName element to the quote/name element.

The mapping of the address data, is a more complex transformation, as represented by the arrow labeled 2 in the preceding figure. To transform the address information, all the attributes of the shipAddress element (street, city, state, and zip) must be converted to a single string XML element called address.

The source XML data is valid to a different XML Schema than the target XML data. As shown in the preceding figure, the example source XML document called PriceQuote.xml is valid to the XML Schema in the PriceQuote.xsd file. Additionally, the example source XML document called Quote.xml is valid to the XML Schema in the Quote.xsd file.

The PriceQuote.xml, AvailQuote.xml, QuoteRequest.xml, QuoteRequest_a.xml, and Quote.xml files are located in the Tutorial_Process_ApplicationWeb/requestquote/testxml directory of the application.

Note: The preceding figure shows just one source data type (priceQuote). This is just one of the three sources to the myJoin method as described in Step 2: Building the Transformation. In this step, the mappings between the XML Schema in the PriceQuote.xsd file to the XML Schema in the Quote.xsd file are discussed. In the Step 4: Mapping Repeating Elements—Creating a Join, mappings between the other source types (AvailQuote.xsd and taxRate) are discussed.

Note: The PriceQuote.xml, AvailQuote.xml, QuoteRequest_a.xml, QuoteRequest.xml, and Quote.xml files are provided as examples and are not used by the business process during run time. During run time, the business process constructs the source XML data, and passes it to the transformation as described in the Introduction of this tutorial.

Complete the following tasks to create, alter, and test mappings between the source and target data:

- To Map a Node From a Source to a Target
- To Map Attributes of an Element to Single Element
- To View and Save the Generated Simple Query
- To Test the Simple Query
- To Edit and Retest the Simple Query
- To Add an XQuery Function Call to the Query

To Map a Node From a Source to a Target

In this step, you map the XML string element called customerName from the source (PriceQuote.xsd) to the XML string element called name in target (Quote.xsd).

1. View myJoin.xq in the Design View:

1. If the Application tab is not visible in WebLogic Workshop, from the menu bar choose View —> Application.
2. In the Application tab, double-click Tutorial_Process_Application\Tutorial_Process_ApplicationWeb\
   requestquote\MyTutorialJoin.dtf\myJoin.xq, then, if necessary, select the Design View tab.

The Design View displays the a graphical representation of the selected sources in the Source pane, as shown in the following figure.

Note: If the priceQuoteDoc, availQuoteDoc, and taxRate nodes are not displayed in your Source pane, follow the instructions in To Select the Source Types.

The nodes displayed in the Source pane correspond to source parameters of the myJoin method of the MyTutorialJoin Transformation file. The signature of the myJoin method from the MyTutorialJoin.dtf file is shown in the following Java code segment:

    /**
     * @dtf:transform xquery-ref="myJoin.xq"
     * @dtf:schema-validate return-value="false" parameters="false"
     */
    public abstract org.example.quote.QuoteDocument myJoin(org.example.price.PriceQuoteDocument priceQuoteDoc,
    org.example.avail.AvailQuoteDocument availQuoteDoc, float taxRate);

For example, the priceQuoteDoc node displayed in the Source pane, corresponds to the org.example.price.PriceQuoteDocument priceQuoteDoc parameter in the myJoin method.

Note: You can view the full source code listing of the MyTutorialJoin Transformation file by double-clicking MyTutorialJoin.dtf in the Application tab, then selecting the Source View tab.

2. From the Source pane of the myJoin XQ file, drag-and-drop the priceQuoteDoc/customerName node onto the quote/name node in the Target pane.

A solid line appears between the two elements. This solid line represents a data link between the two nodes—a link that converts the value of the source node directly to the value of the target node. This link is shown in the following figure.

This link corresponds to the mapping represented with an arrow (labeled with the number 1) in Figure: Mapping Example.

To Map Attributes of an Element to Single Element

In this step, you will map multiple attributes of one element to another single element.

The XML priceQuoteDoc/shipAddress element contains the following attributes:

- street
- city
- state
- zip

All these attributes will be mapped to the single XML quote/address element of type string. This mapping is represented by the arrow labeled 2 in Figure: Mapping Example.

Link the multiple shipAddress attributes from the Source pane to the Target pane with a single drag-and-drop operation, as described in the following procedure:

1. In the Source pane, select the street attribute of priceQuoteDoc/shipAddress node.
2. In the Source pane, press Shift while selecting the zip attribute of the priceQuoteDoc/shipAddress node.

The street, city, state, and zip attributes are selected. The street, city, and state attributes are shaded in gray and the zip attribute is shaded in blue as shown in the following figure.

Note: You can also use the Ctrl key to select groups of nodes.

3. Drag-and-drop the attributes from the Source pane to the quote/address node in the Target pane.

Four new links are displayed, as shown in the following figure.

Figure : Create Links

The links labeled with numbers in the preceding figure, correspond to the mappings represented as arrows (labeled with numbers) in Figure: Mapping Example.

To View and Save the Generated Simple Query

A query (in the XQuery language) is generated when you create mapping links from source elements and attributes to target elements and attributes.

1. Select the Source View tab of the myJoin.xq file.

The generated query is displayed as shown in the following figure.

Note: The XQuery code labeled with numbers in the preceding figure correspond to the numbered mappings and links in Figure: Mapping Example and Figure: Create Links, respectively.

2. Save all the files in this application. From the WebLogic Workshop menu bar, choose File —> Save All. You can also save all the files by entering Ctrl+S.

Note: Pressing Ctrl+S saves all the files in the application, not just the current file.

To Test the Simple Query

This section describes the steps necessary to test the query generated in the preceding section. In this section, you will enter source XML data, run that data against the query, and view the resulting target XML data.

1. Select the Test View tab of myJoin.xq file.
2. Import PriceQuote.xml as source data for the transformation:

1. From the drop-down menu in the Source Data pane, select $priceQuoteDoc.
2. Click Import... .

The Open File to Test dialog box is displayed.

3. Double-click the requestquote folder.
4. Double-click the testxml folder.
5. Click the PriceQuote.xml file.
6. Click Open.

A graphical representation of the PriceQuote.xml file appears in the Source Data pane.

3. In the Result Data pane, click Test.

Note: In order for a query to run, the WebLogic Server for the current application must be running. If not currently running, the WebLogic Server for the current application will be started.

The source XML data in one format is transformed by the query to XML in the target format and graphically displayed in the Result Data pane, as shown in the following figure.

The preceding figure shows a graphical representation of the resulting XML data.

To learn more about the transformation occurring in the query including a walk through of the generated XQuery code, see Understanding the Transformation.

4. To view the resulting data as an XML document, in the Result Data pane, select the XML Source View tab.

The following XML data is displayed:

    <?xml version="1.0" encoding="UTF-8"?>
    <quot:quote xmlns:quot="http://www.example.org/quote">
    	<name>Acme Inc</name>
    	<address>12 Springs RdMorris Plainsnj07960</address>
    </quot:quote>

Note: In the preceding XML document, the string: quot is the namespace prefix for the following namespace URI: xmlns:quot="http://www.example.org/quote". To learn more about namespace declarations and how this XML data was generated, see Understanding the Transformation.

To Edit and Retest the Simple Query

This section provides the steps for editing the generated query to add a delimiter between the street, city, state, and zip code fields of the address element.

1. Select the Design View tab of myJoin.xq file.
2. Select the link between the zip attribute of the priceQuoteDoc/shipAddress node and the quote/address node.

In the General Expression pane of the Target Expression tab, the XQuery code between the nodes is displayed. (If the Target Expression tab is not visible, from the WebLogic Workshop menu bar, choose View —> Windows —> Target Expression tab.)

3. In the General Expression pane of the Target Expression tab, add the argument: ",", between the address attribute parameters of the concat function to delineate between the different address fields, as shown in the following listing:

    concat($priceQuoteDoc/ns0:shipAddress/@street,",",
    $priceQuoteDoc/ns0:shipAddress/@city,",",
    $priceQuoteDoc/ns0:shipAddress/@state,",",
    $priceQuoteDoc/ns0:shipAddress/@zip)

4. Click Apply.

The updated map is displayed as shown in the following figure.

In the proceeding step, you modified the links between shipAddress attributes and the address element in the query, which causes these links to change from direct data links (represented as blue lines) to implied links (represented as light gray lines) as show in the following figure. The mapper parses the XQuery code and determines that there are implied links between the target and source elements.

5. Select the Test View tab of myJoin.xq file and in the Result Data pane click Test.

In the Result Data pane, the resulting XML data is displayed.

The street, city, state, and zip code fields of the address element will be delineated by a commas, as shown in the following listing:

    <address>12 Springs Rd,Morris Plains,nj,07960</address>

To Add an XQuery Function Call to the Query

This section provides steps for converting the state field to uppercase by calling a standard W3C XQuery function from the query.

1. Select the Design View tab of myJoin.xq file.
2. Select the link between the state attribute of the shipAddress element and the quote/address element.

In the Source pane, the state attribute becomes shaded in green.

In the General Expression pane of the Target Expression tab, the call to the concat function is selected, as shown in the following figure.

3. In the General Expression pane, find the following text:

    $priceQuoteDoc/ns0:shipAddress/@state

4. In the Palette, expand the String Functions folder. (If the Palette is not visible, from the WebLogic Workshop menu bar, choose View —> Windows —> Palette.)
5. In the Palette, select the upper-case function, and drag-and-drop it over the $priceQuoteDoc/ns0:shipAddress/@state attribute in the General Expression pane.

The following is displayed in the General Expression pane, as shown in the following figure.

Leave $string-var selected in the General Expression pane as shown in the preceding figure.

6. In the Source pane, select the priceQuoteDoc/shipAddress/state node and drag-and-drop it over the $string-var parameter of the General Expression pane.

In General Expression pane the following is displayed, as shown in the following figure.

7. Click Apply.
8. Select the Test View tab.
9. Click Test.

In the XML Source View tab of the Result Data pane, the state is displayed in uppercase characters, as shown in the following listing:

    <address>12 Springs Rd,Morris Plains,NJ,07960</address>