|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
 Previous |
 Next |
|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
|
Previous |
Next |
This chapter describes features of the XSLT Mapper and provides step-by-step instructions for mapping a sample purchase order schema to an invoice schema.
This chapter contains the following topics:
Transformation use is demonstrated in several Oracle BPEL Process Manager use cases.
|
See:
|
A transform activity enables you to create a transformation using the XSLT Mapper tool. This tool enables you to map source elements to target elements. For example, you can map incoming source purchase order schema data to outgoing invoice schema data. To create a transformation with these mappings, you first drag and drop a transform activity from the Component Palette into your BPEL process diagram, as shown in Figure 14-1.
Figure 14-1 Invoking the Mapper from JDeveloper BPEL Designer
Double-click the transform activity. Figure 14-2 shows the Transform window.
Perform the following procedures
Specify the following information:
Source variable from which to map elements
Source part of the variable (for example, a payload schema consisting of a purchase order request) from which to map
Target variable to which to map elements
Target part of the variable (for example, a payload schema consisting of an invoice) to which to map
Specify a map file name or accept the default name in the Mapper File field. The map file is the file in which you create your mappings using the XSLT Mapper transformation tool.
If the map file already exists, click the flashlight icon (first icon) to browse mappings.
If you select a file with a.xslt extension such as xform.xslt, it opens the mapper pane to create a new XSL file named xform.xslt.xsl, even though your intension was to use the existing xform.xslt file. A .xsl extension is appended to any file that does not already have a .xsl extension, and you must create the mappings in the new file. As a workaround, ensure that your files first have an extension of .xsl. If the XSL file has an extension of .xslt, then rename it to .xsl.
If the map file does not exist, enter a name for the map file in the Mapper File field and click the magic wand icon (second icon) to create a new mapping.
If the map file already exists and you want to edit it, click the note pad icon (third icon) to edit the mapping.
|
See Also: The online Help for the Transform window for detailed descriptions of the fields |
You use the XSLT Mapper transformation tool to create the contents of a map file. Figure 14-3 shows the layout of the XSLT Mapper.
The Source and the Target schemas are represented as trees and the nodes in the trees are represented using a variety of icons. The displayed icon reflects the schema or property of the node. For example:
An XSD attribute is denoted with an icon that is different from an XSD element
An optional element is represented with an icon that is different from a mandatory element
A repeating element is represented with an icon that is different from a nonrepeating element, and so on
The various properties of the element and attribute are displayed in the Property Inspector in the lower right of Figure 14-3 (for example, type, cardinality, and so on). The Functions Palette in the upper right of Figure 14-3 is the container for all functions provided by the XSLT Mapper. The mapper pane or canvas is the actual drawing area for dropping functions and connecting them to source and target nodes.
The XSLT Mapper provides three separate context sensitive menus:
One in the source panel
One in the target panel
One in the mapper pane or canvas in the middle
Right-click in each of the three separate panels to see what the context menus look like. A full set of Undo Auto Map, Redo, Delete, and Delete All functions are also available.
A node in the target tree can be linked only once (that is, you cannot have two links connecting a node in the target tree).
An incomplete function and expression does not result in an XPath expression in the source view. If you switch from the design view to the source view with one or more incomplete expressions, the Mapper Messages window displays warning messages.
When you map duplicate elements in the XSLT Mapper, the style sheet becomes invalid and you cannot work in the Design view. The Log Window shows the following error messages when you map an element with a duplicate name:
Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/ns0:rel" Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:ind" Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:var"
The workaround is to give each element a unique name.
The following steps provide a high level overview of how to create an XSL map using the po.xsd and invoice.xsd files in the Oracle_home\integration\orabpel\samples\demos\XSLMapper directory.
In JDeveloper BPEL Designer, select the workspace project in which you want to create the new XSL map.
Add the po.xsd and invoice.xsd files to the project.
Right-click the selected project and select New.
The New Gallery window appears.
In the Categories tree, expand General and select XML.
In the Items list, double-click XSL Map.
The Create XSL Map File window appears. This window enables you to create an XSL map file that maps a root element of a source schema file or WSDL file to a root element of a target schema file or WSDL file.
Schema files that have been added to the project appear under Project Schema Files.
Schema files that are not part of the project can be imported using the Import Schema File facility. Click the Import Schema File icon (first icon to the right and above the list of schema files).
Under Source, expand Project Schema Files, and then po.xsd. Select PurchaseOrder as the root element for the source.
Under Target, expand Project Schema files, and then invoice.xsd. Select Invoice as the root element for the target.
Click OK.
A new XSL map is created.
The following sections describe how to use 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. Copy the element PurchaseOrder/ID to Invoice/ID and the attribute PurchaseOrder/OrderDate to Invoice/InvoiceDate, as shown in Figure 14-4.
Perform the following steps to set a constant value.
Select a node in the target tree.
Invoke the context menu by right-clicking the mouse.
Select the Set Text menu option.
Enter text in the Set Text window (for example, Discount Applied, as shown in Figure 14-5).
Click OK to save the text.
A T icon is displayed next to the node that has text associated with it.
If you want to remove the text associated with the node, right click the node to invoke the Set Text window again. Delete the contents and click OK.
|
See Also: The online Help for the Set Text window for detailed information |
In addition to the standard XPath 1.0 functions, the Mapper provides a number of prebuilt extension functions and has the ability to support user-defined functions and named templates. The extension functions are prefixed with xp20 or orcl and mimic XPath 2.0 functions.
Perform the following steps to view function definitions and use a function:
Select a category of functions (for example, String Functions) from the Component Palette.
Right-click an individual function (for example, lower-case).
Select Function Description. A window with a description of the function appears. You can also click a link at the bottom to access this function's description at the World Wide Web Consortium at www.w3.org.
Drag a concat function into the mapper pane. This function enables you to connect the source parameters from the source tree to the function and the output of the function to the node on the target tree.
Concatenate PurchaseOrder/ShipTo/Name/First and PurchaseOrder/ShipTo/Name/Last. Place the result in Invoice/ShippedTo/Name by dragging threads from the first and last names and dropping them on the left handle on the concat function. Also drag a thread from the ShippedTo name and connect it to the right handle on the concat function, as shown in Figure 14-6.
|
See Also: The documentation for the XPath extension functions, which is described in Appendix G, "XPath Extension Functions" and is also accessible by clicking Manage BPEL Domain, and then XPath Library in Oracle BPEL Console |
To edit the parameters of the concat function, double-click the function icon to launch the Edit Function - concat window. This window enables you to add, remove, and reorder parameters. If you want to add a new comma parameter so that the output of the concat function is Last, First, then click Add to add a comma and reorder the parameters to get this output.
|
See Also: The online Help for the Edit Function window by clicking the Help button to see how to add, remove, and reorder function parameters |
Complex expressions can be built by chaining functions. To remove all leading and trailing spaces from the output of the above concat function, use the left-trim and right-trim functions and chain them as shown in the Figure 14-8.
The chaining function can also be defined by dragging and dropping the function to a connecting link.
Some complicated mapping logic cannot be represented or achieved by visual mappings. For these situations, named templates are useful. Named templates enable you to share common mapping logic. You can define the common mapping logic as a named template and then use it as often as you want.
You define named templates in the source view, and they appear in the User Defined Named Templates list of the Component Palette. You can use named templates in almost the same way as you use other functions. The only difference is that you cannot link the output of a named template to a function or another named template; you can only link its output to a target node in the target tree.
To write named templates, you must be familiar with the XSLT language. See any XSLT book or visit the following URL for details about writing named templates:
http://www.w3.org/TR/xslt
You can import your own set of Java functions, which appear in the function palette under the User defined Extension Functions category. They can be used like any other function. To add functions, select Preferences, then XSL Maps from the Tools main menu.
|
See Also: Oracle_home\integration\orabpel\samples\demos\XSLMapper\ExtensionFunctions\README.txt for detailed instructions
|
To use an XPath expression in a transformation mapping, select Advanced Functions from the Component Palette and drag and drop xpath-expression from the list into the transformation window, as shown in Figure 14-9.
When you double-click the icon, the Edit XPath Expression window appears, as shown in Figure 14-10. You can press the Ctrl key and then the spacebar to invoke the XPath Building Assistant.
Figure 14-10 Edit XPath Expression Window
Figure 14-11 shows the XPath Building Assistant.
Figure 14-11 The XPath Building Assistant
|
See Also: The online Help for the Edit XPath Expression window, which includes a link to instructions on using the XPath Building Assistant |
While mapping complex schemas, it is sometimes essential to conditionally map a source node to a target or map an array of elements in the source to an array of elements in the target. The XSLT Mapper provides various XSLT constructs in the context sensitive menu of the target tree for the preceding scenarios. To add an XSLT element like for-each, if, or choose to a schema element, select the element in the target tree. Right-click and select Add XSL Node to bring up the context menu and choose the required XSLT element in the menu.
Note that HQAccount and BranchAccount are part of a choice in the PurchaseOrder schema; only one of them exists in an actual instance. To illustrate conditional mapping, copy PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/AccountNumber only if it exists. To do this:
Select Invoice/BilledToAccount/AccountNumber in the target tree and right-click to bring up the context sensitive menu.
Select Add XSL Node, and then if and connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/if.
Connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/if/AccountNumber.
Figure 14-12 shows the results.
Figure 14-12 Conditional Processing with xsl:if
You can copy PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/AccountNumber, if it exists. Otherwise, copy PurchaseOrder/BranchAccount to Invoice/BilledToAccount/AccountNumber as follows:
Select Invoice/BilledToAccount/AccountNumber in the target tree and right-click to bring up the context sensitive menu.
Select Add XSL Node, and then choose and connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/choose/when to define the condition.
Connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/choose/when/AccountNumber.
Select XSL Add Node and then choose in the target tree and right-click to bring up the context sensitive menu.
Select Add XSL node and then otherwise from the menu.
Connect PurchaseOrder/BranchAccount/AccountNumber to Invoice/BilledToAccount/choose/otherwise/AccountNumber.
Figure 14-13 shows the results.
Figure 14-13 Conditional Processing with xsl:choose
The XSLT Mapper allows repeating elements on the source to be copied to repeating elements on the target. For example, copy PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/Item as follows:
Select Invoice/ShippedItems/Item in the target tree and right-click to bring up the context sensitive menu.
Select Add XSL Node, and then for-each and connect PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/for-each to define the iteration.
Connect PurchaseOrder/Items/HighPriorityItems/Item/ProductName to Invoice/ShippedItems/for-each/Item/ProductName.
Connect PurchaseOrder/Items/HighPriorityItems/Item/Quantity to Invoice/ShippedItems/for-each/Item/Quantity.
Connect PurchaseOrder/Items/HighPriorityItems/Item/USPrice to Invoice/ShippedItems/for-each/Item/PriceCharged.
Figure 14-14 shows the results.
Figure 14-14 Handling Repetition or Arrays
|
Note: Executing an auto map automatically inserts xsl:for-each. To see the auto map in use, drag and drop PurchaseOrder/Items/LowPriorityItems to Invoice/UnShippedItems; for-each is automatically created. |
Mapping nonleaf nodes starts the auto map feature. The system automatically tries to link all relevant nodes under the selected source and target. Try the auto map feature by mapping PurchaseOrder/ShipTo/Address to Invoice/ShippedTo/Address. All nodes under Address are automatically mapped, as shown in Figure 14-15.
The behavior of the auto map can be tuned by altering the settings in JDeveloper BPEL Designer preferences or by right-clicking the transformation window and selecting Auto Map Preferences. This displays the window shown in Figure 14-16.
This window enables you to customize your auto mapping as follows:
Invoke the automatic mapping feature, which attempts to automatically link all relevant nodes under the selected source and target. When disabled, you must individually map relevant nodes.
Display and review all potential source-to-target mappings detected by the XSLT Mapper, and then confirm to create them.
Be prompted to customize the auto map preferences before the auto map is invoked.
Select the Basic or Advanced method for automatically mapping source and target nodes. This enables you to customize how the XSLT mapper attempts to automatically link all relevant nodes under the selected source and target.
Manage your dictionaries. The XSLT Mapper uses the rules defined in a dictionary when attempting to automatically map source and target elements.
|
See Also: The online Help for the Auto Map Preferences window by clicking the Help button to see a description of the fields |
To see potential source mapping candidates for a target node, right-click the target node, select Show Matches, and click OK in the Auto Map Preferences window. The Auto Map window appears, as shown in Figure 14-17.
|
See Also: The online Help for the Auto Map window by clicking the Help button to see a description of the fields |
When the Confirm Auto Map Results check box shown in Figure 14-16 is selected, a confirmation window appears. If matches are found, the potential source-to-target mappings detected by the XSLT Mapper are displayed, as shown in Figure 14-18. The window enables you to filter one or more mappings.
|
See Also: The online Help for the Auto Map window by clicking the Help button to see a description of the fields |
The auto map confirmation window can also be turned on or off with Confirm Auto Map Links in the context menu of the mapper pane, as shown in Figure 14-19.
Figure 14-19 Confirm Auto Map Links Selection
You can view a list of target nodes that are currently unmapped to source nodes. Right click in the mapper pane and select Completion Status. This window provides statistics at the bottom about the number of unmapped target nodes. This window enables you to identify and correct any unmapped nodes before you test your transformation mapping logic on the Test XSL Map window. Select a target node in the list. The node is highlighted. A check mark indicates that the target node is required to be mapped. If not required, the check box is empty.
Figure 14-20 provides an example of the Completion Status window.
A dictionary is an XML file that captures the synonyms for mappings. Right-click the mapper pane as shown in Figure 14-19 and select Generate Dictionary. This prompts you for the dictionary name and the directory in which to place the dictionary. The XSLT Mapper uses the rules defined in the dictionary when attempting to automatically map source and target elements. For example, you may want to map a purchase order to a purchase order acknowledgment, then reuse most of the map definitions later.
Build all the mapping logic for the purchase order and purchase order acknowledgment.
Generate a dictionary for the created map.
Create a new map using a different purchase order and purchase order acknowledgment.
Load the previously created dictionary by selecting Preferences, then XSL Maps, then Auto Map in the Tools main menu of JDeveloper BPEL Designer.
Perform an automatic mapping from the purchase order to the purchase order acknowledgment.
When the XSLT Mapper encounters any elements in the XSLT document that cannot be found in the source or target schema, it is unable to process them and displays an Invalid Source Node Path error. XSL map generation fails. You can create and import a file that directs the XSLT Mapper to ignore and preserve these specific elements during XSLT parsing by selecting Preferences, then XSL Maps in the Tools main menu of JDeveloper BPEL Designer.
For example, preprocessing may create elements named myElement and myOtherElementWithNS that you want the XSLT Mapper to ignore when it creates the graphical representation of the XSLT document. You create and import a file with these elements to ignore that includes the following syntax:
<elements-to-ignore> <element name="myElement"/> <element name="myOtherElementWithNS" namespace="NS"/> </elements-to-ignore>
You must restart JDeveloper BPEL Designer after importing the file.
You can replace the map source schema and map target schema that currently display in the XSLT Mapper. Right click in either the source or target panel and select Replace Schema. This opens the Select Source and Target Schema window, which enables you to select the new source or target schema to use.
The XSLT Mapper provides a test utility to test the style sheet or map. The test tool can be invoked by selecting the Test menu item from the mapper pane context sensitive menu, as shown in Figure 14-21.
The Open button is used to load a sample XML instance file for testing. If you do not have a source file or if you prefer the system to generate a random source instance, you can click the Generate button. After you have a sample source instance, you can generate the result document by clicking Test, as shown in Figure 14-22. This enables the Target XML section to display the target XML.
|
Note: By default, the Xalan XSL processor is used for testing XSL mappings, If you want to use the Oracle XSL Processor to test mappings, select Preferences, then XSL Maps in the Tools main menu of JDeveloper BPEL Designer to change this setting in the Preferences window. |
You can generate an HTML report with the following information:
XSL map file name, source and target schema file names, their root element names, and their root element namespaces
Target document mappings
Target fields not mapped (including mandatory fields)
Sample transformation map execution
To generate a report, right-click the transformation window and select Generate Report. The Generate Report window appears in the transformation window, as shown in Figure 14-23.
|
See Also: The online Help for the Generate Report window by clicking the Help button to see detailed information |
If you attempt to generate a report and receive an out-of-memory error, increase the heap size of the JVM as follows:
Open the Oracle_Home\integration\jdev\jdev\bin\jdev.conf file.
Go to the following section:
# Set the maximum heap to 512M # AddVMOption -Xmx512M
Increase the size of the heap as follows (for example, to 1024)
AddVMOption -Xmx1024M
In addition, you can also uncheck the Open Report option on the Generate Report window before generating the report.
You can customize sample XML generation by specifying the following parameters. Select Preferences, then XSL Maps in the Tools main menu of JDeveloper BPEL Designer to display the Preferences window.
Specifies how many occurrences of an element are created if the element has the attribute maxOccurs set to a value greater than 1. If the specified value is greater than the value of the maxOccurs attribute for a particular element, the number of occurrences created for that particular element is the maxOccurs value, not the specified number.
If selected, any optional element (its attribute minOccurs set to a value of 0) is generated the same way as any required element (its attribute minOccurs set to a value greater than 0).
To avoid the occurrence of recursion in sample XML generation caused by optional elements, specify a maximum depth in the XML document hierarchy tree beyond which no optional elements are generated.
This chapter describes features of the XSLT Mapper, such as:
Creating an XSL map file
Copying by linking nodes
Creating functions
Chaining functions
Editing XPath expressions
Adding XSLT constructs such as if, choose, otherwise, and for-each
Automatically mapping target and source nodes
Viewing unmapped target nodes
Generating dictionaries
Ignoring elements in an XSLT document
Replacing schemas in the XSLT Mapper
Testing mappings
Generating mapping reports
This chapter shows these features by providing step-by-step instructions for mapping a sample purchase order schema to an invoice schema.
