7.5 Creating a Transformation

A transformation maps the elements of a source schema to the elements of a target schema. Because a web service typically specifies the format required for incoming data, for example, the format of an invoice, you need a transformation to map the source data schema, for example, a purchase order, to the target data schema.

You use the transform activity to add transformation logic to a BPEL process. The transformation defines the source and target variables, the message parts to map, and the XSL map file. To specify the source and target schema mapping, you use the XSLT Mapper, shown in Figure 7-12.

Figure 7-12 The XSLT Mapper

Description of "Figure 7-12 The XSLT Mapper "

The source and target schemas that you identify when creating the XSL map are displayed in the XSLT Mapper. To copy an attribute or leaf-element in the source to an attribute or leaf-element in the target, drag and drop the source to the target. To do more complex mappings, drag and drop functions into the mapper canvas (in the center) and connect the functions to the source and target nodes. From the Component Palette, the following mapping functionality is available:

Advanced functions: Examples of these functions are lookup-xml, which looks up values in XML files, and xpath-expression, with which you can build an XPath expression into the mapping.
Code snippets: Enables you to add Java code to the mapping.
Conversion functions: Examples are boolean, which converts a parameter to a Boolean, and string, which converts a parameter to a string.
Cumulative functions: Enables you to count or sum the nodes in a node set.
Database functions: Enables you to query a database.
Date functions: Examples include current-date, which returns the current date in ISO format, and implicit-timezone which returns the current time zone in ISO format.
Logical functions: Examples include logical and and or, and the functions for comparing parameters, such as greater and less.
Mathematical functions: Examples include abs, which returns the absolute value of the input number, and arithmetic operations such as add, subtract, multiply, and divide.
Node-set functions: Examples include current, which returns a node set that has the current node as its only member, and document, which provides access to XML documents other than the main source document.
String functions: Examples include concat, which returns the concatenation of two strings (for example, concatenate first and last name elements and map them to a target fullname element), and lower-case, which returns an input string with all characters converted to their lower-case equivalents.
User-defined extension functions: You can import your own set of Java functions. From the Tools menu, select Preferences, and then XSL Maps.
User-defined named templates: For a complex mapping, you can define a template in the XSLT language, which you then use like a function.
XML: You can manipulate the XML content, or get information about it.
XSLT constructs: Examples include xsl:if, which enables you to apply a condition in your map (for example, map a source to a target only if it exists), and for-each, which maps repeating elements in the source to repeating elements in the target (useful for handling arrays).
WC3-recommended XSLTs: Examples include xsl:element, in which an element is created with a computed name, and xsl:attribute, in which an element is used to add attributes to result elements. For a description of the XSLTs recommended by the World Wide Web Consortium, go to
```
www.w3.org/1999/Transform
```

BPEL processes and ESB projects can use the same XSLT.

The Property Inspector, shown in Figure 7-13, displays the properties of a selected XSD element.

Figure 7-13 Property Inspector

Description of "Figure 7-13 Property Inspector"

See Oracle BPEL Process Manager Developer's Guide for information on the following transformation and XSLT Mapper topics:

Examples using the XSLT Mapper and context-sensitive menus, including how to set constant values, use extension functions, edit function parameters, chain functions, and edit XPath expressions
How to create XSL map files without using the XSLT Mapper
How to map nodes automatically using the Auto Map Preferences feature
How to generate mapping dictionaries (synonyms for mappings) using the Generate Dictionary feature and HTML reports using the Generate Report feature
How to test a map

7.5.1 How to Create a Transformation

To create a transformation, use a transform activity and the XSLT Mapper, which assigns elements of a source schema to the elements of a target schema.

To create a transformation:

Drag and drop a Transform activity into the BPEL process.
Double-click the Transform activity.
Use the Transform dialog (shown in Figure 7-14) to enter source and target schema information.

Figure 7-14 Creating a Transformation

Description of "Figure 7-14 Creating a Transformation"
1. Select the source variable from which to map elements.
2. Select the source part of the variable (for example, a payload schema consisting of a purchase order request) from which to map.
3. Select the target variable where elements are mapped to.
4. Select the target part of the variable (for example, a payload schema consisting of an invoice) to which to map.
5. Enter a mapper file name or accept the default name (or use the flashlight icon to browse for a file).
  
  This file stores the mapping you create using the XSLT Mapper transformation tool.
6. Click the Create Mapping icon.
7. Use the XSLT Mapper to drag and drop from source attributes or leaf-elements to target attributes or leaf-elements, as shown in Figure 7-12. Use the functions in the Component Palette and the automap feature to simplify this task.

You can also create an XSL map file from an XSL stylesheet. From the File main menu in Oracle JDeveloper, click New, then XML, and then XSL Map From XSL Stylesheet.

See Oracle BPEL Process Manager Order Booking Tutorial for step-by-step instructions on dragging from source to target in the XSLT Mapper.

7.5.2 What Happens When You Create a Transformation

When you use the XSLT mapper, the transformation is captured in an XSL map file. Example 7-5 shows the source code for TransformOrder.xsl, which maps the order schema in SOAOrderBooking.wsdl to the database schema required by the Order web service.

Example 7-5 Source Code for TransformOrder.xsl

<?xml version="1.0" encoding="UTF-8" ?>
<?oracle-xsl-mapper
  <!-- SPECIFICATION OF MAP SOURCES AND TARGETS, DO NOT MODIFY. -->
  <mapSources>
    <source type="WSDL">
      <schema location="SOAOrderBooking.wsdl"/>
      <rootElement name="SOAOrderBookingProcessRequest" namespace="http://
        www.globalcompany.com/ns/OrderBooking"/>
    </source>
  </mapSources>
  <mapTargets>
    <target type="XSD">
      <schema location="Order_table.xsd"/>
      <rootElement name="OrdersCollection" namespace="http://
        xmlns.oracle.com/pcbpel/adapter/db/top/Order"/>
    </target>
  </mapTargets>
  <!-- GENERATED BY ORACLE XSL MAPPER 10.1.3.1.0(build 060515.0101) AT [SAT JUL 08 16:58:22 PDT 2006]. -->
?>
<xsl:stylesheet version="1.0"
                xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
                xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
                xmlns:ns1="http://xmlns.oracle.com/SOAOrderBooking"
                xmlns:ns4="http://www.globalcompany.com/ns/OrderBooking/rules"
                xmlns:ns0="http://www.w3.org/2001/XMLSchema"
                xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
                xmlns:xp20="http://www.oracle.com/XSL/Transform/java/
                  oracle.tip.pc.services.functions.Xpath20"
                xmlns:client="http://www.globalcompany.com/ns/OrderBooking"
                xmlns:ns2="http://xmlns.oracle.com/pcbpel/adapter/db/top/Order"
                xmlns:cu="http://www.globalcompany.com/ns/customer"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:po="http://www.globalcompany.com/ns/order"
                xmlns:wf="http://schemas.oracle.com/xpath/extension"
                xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
                xmlns:orcl="http://www.oracle.com/XSL/Transform/java/
                  oracle.tip.pc.services.functions.ExtFunc"
                exclude-result-prefixes="xsl plnk ns4 ns0 client po ns2 bpws hwf xp20 wf ids orcl">
  <xsl:template match="/">
    <ns3:OrdersCollection>
      <ns3:Orders>
        <ns3:comments>
          <xsl:value-of select="/client:SOAOrderBookingProcessRequest/po:PurchaseOrder/
            po:OrderInfo/po:OrderComments"/>
        </ns3:comments>
        <ns3:itemsCollection>
          <xsl:for-each select="/client:SOAOrderBookingProcessRequest/po:PurchaseOrder/
            po:OrderItems/po:Item">
            <ns3:Items>
              <ns3:partnum>
                <xsl:value-of select="po:partnum"/>
              </ns3:partnum>
              <ns3:price>
                <xsl:value-of select="po:price"/>
              </ns3:price>
              <ns3:productname>
                <xsl:value-of select="po:ProductName"/>
              </ns3:productname>
              <ns3:quantity>
                <xsl:value-of select="po:Quantity"/>
              </ns3:quantity>
            </ns3:Items>
          </xsl:for-each>
        </ns3:itemsCollection>
      </ns3:Orders>
    </ns3:OrdersCollection>
  </xsl:template>
</xsl:stylesheet>