| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
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:
SOA_Oracle_home\bpel\samples\demos\XSLMapper
SOA_Oracle_home\bpel\samples\tutorials\114.XSLTTransformations
Transformations are performed in an XSL map file in which you map source schema elements to target schema elements. This section describes two methods for creating the XSL map file:
Note:
You can also create an XSL map file from an XSL stylesheet. Click New > General > XML > XSL Map From XSL Stylesheet from the File main menu in Oracle JDeveloper.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.
Drag and drop a transform activity from the Component Palette into your BPEL process diagram.
Double-click the transform activity.
The Transform window appears.
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.
Click the magic wand icon (second icon) to create a new mapping. If the file already exists, click the note pad icon (third icon) to edit the mapping.
The XSLT Mapper appears.
Go to "Overview of the XSLT Mapper" for an overview of using the XSLT Mapper.
Note:
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.The following steps provide a high level overview of how to create an XSL map using the existing po.xsd and invoice.xsd files in the SOA_Oracle_home\bpel\samples\demos\XSLMapper directory.
In Oracle JDeveloper, select the application project in which you want to create the new XSL map.
Import the po.xsd and invoice.xsd files into the project (for example, by right-clicking Schemas and selecting Import Schemas in the Structure section of Oracle JDeveloper).
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).
Enter a name for the XSL map file in the File Name field.
Under Source, expand Project Schema Files > po.xsd > PurchaseOrder as the root element for the source.
Under Target, expand Project Schema files > invoice.xsd > Invoice as the root element for the target.
Click OK.
A new XSL map is created.
Save and close the file now or begin to design your transformation. Information on using the XSLT Mapper tool is provided in "Overview of the XSLT Mapper".
Drag and drop a transform activity from the Component Palette into your BPEL process.
Double-click the transform activity.
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
Click the flashlight icon (first icon) to the right of the Mapper File field to browse for the map file name you specified in Step 6.
Click Open.
Click OK.
The XSLT Mapper displays your XSL map file.
Go to "Overview of the XSLT Mapper" for an overview of using the XSLT Mapper.
You use the XSLT Mapper transformation tool to create the contents of a map file. Figure 13-1 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 13-1 (for example, type, cardinality, and so on). The Functions Palette in the upper right of Figure 13-1 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 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 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 13-2.
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 13-3).
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 informationIn 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 Help. 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 side on the concat function. Also drag a thread from the ShippedTo name and connect it to the right side on the concat function, as shown in Figure 13-4.
See Also:
The documentation for the XPath extension functions, which is described in Appendix D, "XPath Extension Functions"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 parametersComplex 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 13-6.
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 > XSL Maps from the Tools main menu.
See Also:
SOA_Oracle_home\bpel\samples\demos\XSLMapper\ExtensionFunctions\README.txt for detailed instructionsTo 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 13-7.
When you double-click the icon, the Edit XPath Expression window appears, as shown in Figure 13-8. You can press the Ctrl key and then the spacebar to invoke the XPath Building Assistant.
Figure 13-9 shows 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 AssistantWhile 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:
Elements that display in the XSLT Constructs list and http://www.w3.org/1999/XSL/Transform list of the Component Palette cannot be dragged and dropped into the designer window.See Also:
Oracle BPEL Process Manager Order Booking Tutorial for an example of using a for-each nodeNote 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 13-10 shows the results.
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 13-11 shows the results.
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 13-12 shows the results.
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 13-13.
The behavior of the auto map can be tuned by altering the settings in Oracle JDeveloper preferences or by right-clicking the transformation window and selecting Auto Map Preferences. This displays the window shown in Figure 13-14.
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 fieldsTo 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 13-15.
See Also:
The online Help for the Auto Map window by clicking the Help button to see a description of the fieldsWhen the Confirm Auto Map Results check box shown in Figure 13-14 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 13-16. 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 fieldsYou 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 13-17 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 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 > XSL Maps > Auto Map in the Tools main menu of Oracle JDeveloper.
Perform an automatic mapping from the purchase order to the purchase order acknowledgment.
You can create map parameters and variables. You create map parameters in the source tree and map variables in the target tree.
Note the following issues:
Parameters are created in the source tree, are global, and can be used anywhere in the mappings.
Variables are created in the target tree, and are either global or local. Where they are defined in the target tree determines if they are global or local.
Global variables are defined immediately below the <target> node and immediately above the actual target schema (for example, POAcknowledge). Right-click on the <target> node to create a global variable.
Local variables are defined on a specific node below the actual target schema (for example, subnode name on schema POAcknowledge). Local variables can have the same name as long as they are in different scopes. Local variables can only be used in their scopes, while global variables can be used anywhere in the mappings.
Right-click the source tree root and select Add Parameter.
The Create Parameter window appears.
Specify details:
Click OK.
Right-click the target tree root and select Add Variable. If you right-click a node below the target tree root, select Insert Variable.
The Create Variable window appears.
Specify details:
Click OK.
You can search source and target nodes. For example, you can search in a source node named invoice for all occurrences of the subnode named price.
Right-click a source or target node.
Enter a keyword for which to search.
Specify additional details, as necessary. For example:
Select Search Annotations if you want annotations text to also be searched.
Specify the scope of the search. You can search the entire source or target tree, search starting from a selected position, or search within a selected subtree.
The first match found is highlighted, and the Find window closes. If no matches are found, a message displays on-screen.
Select the F3 key to find the next match in the direction specified. To search in the opposite direction, select the Shift and F3 keys.
Note:
You cannot search on functions or text values set with the Set Text option.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 > XSL Maps in the Tools main menu of Oracle JDeveloper.
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 Oracle JDeveloper 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 shown in Figure 13-18, 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, as shown in Figure 13-19.
The Test XSL Map window shown in Figure 13-20 enables you to test the transformation mapping logic you designed with the XSLT Mapper. The test settings you specify are stored and do not need to be entered again the next time you test. Test settings must be entered again if you close and reopen Oracle JDeveloper.
Choose to allow a sample source XML file to be generated for testing or click Browse to specify a different source XML file in the Source XML File field.
When you click OK, the source XML file is validated. If validation passes, transformation occurs, and the target XML file is created.
If validation fails, no transformation occurs and a message displays on-screen.
Select the Generate Source XML File check box to create a sample XML file based on the map source XSD schema.
Select the Show Source XML File check box to display the source XML file for the test. The source XML file displays in an Oracle JDeveloper XML editor.
If the map has defined parameters, the Parameters table appears. If you want to specify a value, click Specify Value and make appropriate edits to the Type and Value columns.
Enter a file name in the Target XML File field or browse for a file name in which to store the resulting XML document from the transformation.
Select the Show Target XML File check box to display the target XML file for the test. The target XML file displays in an Oracle JDeveloper XML editor.
If you select to show both the source and target XML, you can customize the layout of your XML editors. Select Enable Auto Layout in the upper right corner and click one of the patterns.
Click OK.
The test results appear.
For this example, the source XML and target XML display side-by-side, with the XSL map underneath (the default setting). You can right-click an editor and select Validate XML to validate the source or target XML against the map source or target XSD schema.
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 13-21. Note that if the map has defined parameters, the Parameters table appears.
See Also:
The online Help for the Generate Report window by clicking the Help button to see detailed informationIf you attempt to generate a report and receive an out-of-memory error, increase the heap size of the JVM as follows:
Open the JDev_Oracle_Home\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 > XSL Maps in the Tools main menu of Oracle JDeveloper 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
Creating map parameters and variables
Searching source and target nodes
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.
