20 Transforming Data with XSLT

This chapter provides an overview of eXtensible Stylesheet Language Transformation (XSLT) and how it is used in Service Bus services to map XML input to XML output. It also describes how to create XSLT maps in Service Bus projects.

This chapter includes the following sections:

• Introduction to XSLT

• XSLT Editors and Mappers

• Creating XSLT Mappings in JDeveloper

• Working with XSLT Resources in the Oracle Service Bus Console

• How to Open the XSLT Mapper from the Service Bus Console

• How to Delete an XSLT Resource

For more in-depth information about the XSLT mapper in JDeveloper, see Creating Transformations with the XSLT Map Editorin Developing SOA Applications with Oracle SOA Suite.

20.1 Introduction to XSLT

Transformation maps describe the mapping between two data types. eXtensible Stylesheet Language Transformation (XSLT) maps describe mappings between XML documents with different schemas.

Using XSLT, Service Bus can process XML documents and transform document data from one XML schema to another, enabling data interchange among applications that use different schemas. You can perform complex data manipulation and transformation using XSLT. For example, you can map an incoming purchase order schema to an outgoing invoice schema.

20.2 XSLT Editors and Mappers

JDeveloper provides both an Expression Builder, where you can script transformations using XQuery, and an XSLT Mapper, where you can create complex mappings. The Oracle Service Bus Console provides an editor for scripting transformations using XQuery and an XSLT Mapper, where you can create complex mappings.

These editors provide options to define an XQuery expression, to specify an XSLT resource to execute, or to define an expression that evaluates at runtime to the name of an existing XSLT resource. For both JDeveloper and the console, you access the editors from an action in either a pipeline or split-join.

20.2.1 JDeveloper Editors and Mappers

The XSLT mapper in JDeveloper is a graphical tool that lets you define mappings between schema root elements, WSDL message parts, or WSDL messages. Schema root elements can come from XSD schema files or WSDL files, but only those WSDL messages that contain a single message part can be mapped directly. Once you create an XSLT mapping in JDeveloper, you can upload the .xsl file generated by the mapper to an XSLT resource in the Oracle Service Bus Console.

JDeveloper also includes a variety of Expression Builders, where you can create expressions that specify an existing XSLT resource to use. For more information about the mapper and editors in JDeveloper, see the following topics:

• "Creating Transformation with the XSLT Map Editor" in Developing SOA Applications with Oracle SOA Suite

• "Building XPath Expressions in the Expression Builder in Oracle JDeveloper" in Developing SOA Applications with Oracle SOA Suite

20.2.2 Oracle Service Bus Console Editors and Mappers

In the Oracle Service Bus Console, the XQuery/XSLT Expression Editor lets you create expressions that specify an existing XSLT resource to use. Before you can reference an XSLT resource, you need to create the resource in the console and either upload an existing XSL transformation to the resource or create a XSL transformation using the new web-based XSLT Mapper included with Service Bus. This feature allows you to create complex mappings using JDeveloper to import into the console or using the Service Bus console directly. You can reuse an XSL transformation in multiple pipelines and split-joins.

For information about the XQuery/XSLT Editor in the Oracle Service Bus Console, see Working With Expression Editors in Oracle Service Bus Console.

20.3 Creating XSLT Mappings in JDeveloper

You can create XSLT mappings in a Service Bus project in JDeveloper, and then use them in XQuery expressions in pipelines and split-joins to map objects between external systems.

When you create an XSLT mapping, you need to select the source XML schema elements or XML files to use for the source and target mappings.

20.3.1 How to Create XSLT Mappings in JDeveloper

To create an XSLT mapping in JDeveloper:

1. In the Application Navigator in JDeveloper, right-click the Service Bus project or folder in which you want to create the mapping.

2. In the menu that appears, point to New and select XSL Map.

   The Create XSL Map File dialog appears.

3. In the File Name field, enter a unique name for the XSLT map file.

4. Optionally enter a new directory location and a brief description for the cross reference.

   The location must be within the directory structure of the current application.

5. To define the source schema, do the following:

   1. Select Use Source Schema.

   2. Click Browse next to the Primary Source field.

   3. On the Select Schema dialog, select whether to use an XML schema or to generate the source directly from an XML file.

   4. Click Browse in the section you chose above to navigate to and select the XML schema element or file to use.

      You can select an XML schema element from the current application. You can select an XML file from the file system.

   5. When you have selected the schema element or file, click OK on the Select Schema dialog.

   6. To select additional sources to use as parameters, click Add Schema above the Additional Sources table.

6. To define the target schema, select Use target schema, and repeat the above steps on the Select Schema dialog to select the XML components to use.

7. Click OK on the Create XSL Map File dialog.

   The XSLT Mapper appears with the source and target structures displayed.

8. To define the mapping logic, see "Editing an XSLT Map in Map Mode" in Developing SOA Applications with Oracle SOA Suite.

20.4 Working with XSLT Resources in the Oracle Service Bus Console

In the Oracle Service Bus Console, XSLT maps are stored in XSLT resources, which can be reused in any pipelines and split-joins in the current session. You can upload existing XSLT maps into the XSLT resources, and use a text editor to edit them.

• How to Create XSLT Resources in the Console

• How to Edit XSLT Resources in the Console

20.4.1 How to Create XSLT Resources in the Console

If you are using the Oracle Service Bus Console, you can add XSL transformations that you first create in JDeveloper and that you then import into a Service Bus project or upload into an XSL transformation resource. For information on importing, see Importing and Exporting Resources and Configurations . You can also use the XSLT Mapper included with the console to create a new mapping. Use the procedure below to create a new XSLT resource, into which you can import an existing mapping or create a new mapping using the console.

Before you Begin

• If you want to upload an existing XSL transformation map created in JDeveloper, create the XSL transformation mapping file as described in Creating XSLT Mappings in JDeveloper.

• If you want to create a new mapping, ensure that the source and target schemas are already accessible from the Service Bus console. See How to Create XML Schemas for more information.

To create an XSLT resource in the console:

1. In the Project Navigator, right-click the project or folder to contain the new XSL transformation, point to Create, and select Resource. From the Resource Gallery, point to Transformations, select XSLT, and then click OK.

   The Create Schema dialog appears.

2. Do one of the following:

   • To create the resource from an existing XSL mapping file, click Browse next to the File Upload field and then navigate to and select the file you created in JDeveloper. Deselect the Generate Mapping option.

     The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.

   • To create a new XSL transformation, enter a unique name for the transformation resource. Ensure that the Generate Mapping option is selected.

3. Optionally, enter a brief description of the resource.

4. Click Create.

5. If you are creating a new mapping, enter the following information on the Select Source and Target dialog:

   1. Search for and select the source and target schemas using the Search icons in the Source Schema and Target Schema fields. These schemas must already be accessible from the Service Bus console. See How to Create XML Schemas for more information.

   2. Select the source root element for the mapping from the Source Root Element list. This list is populated after the Source Schema is selected.

   3. Select the target root element for the mapping from the Target Root Element list. This list is populated after the Target Schema is selected.

   4. Click OK.

      The XSLT parameters, if defined, appear in the XSLT Definition Editor.

6. To modify the schema, do the following:

   1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

   2. To browse to and select a new mapping file to upload, click Browse.

   3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

   4. Click Save.

7. If you are creating a new mapping, see How to Open the XSLT Mapper from the Service Bus Console for information about using the mapper.

8. In the XSLT Definition Editor toolbar, click Save.

9. To end the session and deploy the configuration to the runtime, click Activate.

20.4.2 How to Edit XSLT Resources and Upload XSL Transformations in the Console

The Oracle Service Bus Console lets you edit an XSLT resource directly or update the contents by uploading a new or updated file.

To edit an XSL transformation in the console:

1. In the Project Navigator, expand the project and folders containing the XSL transformation to edit.
2. Right-click the XSL transformation name, and select Open.
3. Click Edit Source in the toolbar.

   The Edit Source dialog appears.

4. To browse to and select a new XSL transformation file to upload, click Browse.
5. To modify the contents of the file, update the code directly in the Contents section of the dialog.
6. Click Save.
7. In the XSLT Definition Editor toolbar, click Save.
8. To end the session and deploy the configuration to the runtime, click Activate.

20.5 Using the XSLT Mapper in the Service Bus Console

The following topics describe using the XSLT Mapper in the Service Bus Console.

Topics

• How to Open the XSLT Mapper from the Service Bus Console

• Using the Oracle Mapper

20.5.1 How to Open the XSLT Mapper from the Service Bus Console

You access the XSLT mapper from the XSLT Definition Editor.

To open the XSLT Mapper from the Service Bus console, click the Tools icon, and then click Launch Mapper, as shown in the following image.
Description of the illustration GUID-5D4058E3-C300-4535-90F7-4E5F3DDAE4AB-default.png

Note:

You can only edit the mapping when a session is being edited. If you launch the mapper without an active session, the mapper will launch in read only mode. Changes to the mapping cannot be made in read only mode.

The XSLT Mapper launches in a new window.

20.5.2 Using the Oracle Mapper

XSLT Mapper topics are available in Using the Oracle Mapper.

20.6 How to Delete an XSLT Resource

If any resources reference the XSLT resource you want to delete, remove those references before deleting the resource.

In the Oracle Service Bus Console, open the XSLT resource in the XSLT Definition Editor and click the Tools icon in the upper right, and then select References to find out whether it has any references. In JDeveloper, right-click the XSLT resource and select Explore Dependencies.

You can delete the transformation even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

To delete an XSLT resource:

1. In the Application Navigator or Project Navigator, expand the project and folders containing the XSL transformation to delete.
2. Right-click the name of the transformation, and select Delete.
3. If you are using JDeveloper, a confirmation dialog displays the number of references for the transformation. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.