Developing Transforms Using Oracle XSL Mapper

Oracle America has developed a tool that enables you to graphically map records and fields and that creates the underlying XSLT transformation code for you. You launch this tool directly from a PeopleSoft application engine transformation program. When you save the XSLT code in Oracle XSL Mapper, it automatically gets saved to the application database and your application engine transform program.

Oracle XSL Mapper is an Oracle JDeveloper plug-in. Check the My Oracle Support website for information about supported versions.

See Oracle Website.

Note the following as you develop transformations using Oracle XSL Mapper:

• When you save XSL maps that you create in the mapper, the underlying XSL code is automatically saved to the application engine program.

• The mapper does not support codesets and working storage constructs. You must add these constructs manually into the XSL code using the Source view of the mapper.

To use Oracle XSL Mapper you must:

• Install Oracle JDeveloper.

  Oracle XSL Mapper is part of Oracle JDeveloper .

  See Installing Oracle XSL Mapper.

• In PeopleSoft Configuration Manager, specify the path to the Oracle JDeveloper installation location.

  See Specifying the Installation Path and Classpath for Oracle XSL Mapper.

• All messages used in the mapper must have schemas generated for them.

  For rowset-based messages, use the Message Definitions – Schema page to generate schemas. For nonrowset-based messages, use the Message Definitions – Schema page to add or import schemas for these types of messages.

  See Managing XML Message Schemas for Rowset-Based MessagesAdding XML Message Schemas to Nonrowset-Based Messages.

• You must create a Transform Only application engine program and define the program properties described earlier in this topic.

  See Defining a Transform Program.

• If you are using Oracle JDeveloper 11g, the JDK folder and its contents must exist inside the JDeveloper home location. Therefore you must install JDK 1.6 or use an existing installation of JDK 1.6, and copy all the contents inside the <JDEV_HOME> directory. The following example shows the installation path: <JDEV11_HOME>/jdk/<jdk_copied_contents>

• If you are using Oracle 11gR2 or a later release, you must move the following folders from <Middleware_Home>\oracle_common\modules to <Middleware_Home>\jdeveloper\modules:

  • \oracle.xdk_11.1.0

  • \oracle.xmlef_11.1.1

  • \oracle.javatools_11.1.1

Oracle XSL Mapper is a tool that provides the ability to rapidly create XSL-based transformation maps to support integration of PeopleSoft to third-party applications deployed through Integration Broker. The Oracle XSL Mapper is included in Oracle JDeveloper. Access to this feature requires the download of Oracle JDeveloper at the location below.

See Oracle Website.

For Oracle XSL mapper to function, the JDeveloper installation location and classpath must be specified in the PeopleSoft system in the PeopleSoft Configuration Manager. You enter this information on the Configuration Manager – Bus. Interlinks/JDeveloper page.

To specify the path to the Oracle XSL Mapper installation location and classpath:

1. Open PeopleSoft Configuration Manager (pscfg.exe).

2. Click the Bus. Interlink/JDeveloper tab.

3. Locate the JDeveloper Home Directory section at the bottom of the page.

4. In the JDeveloper Home field, enter the path or browse to the location where JDeveloper is installed.

5. Click the Apply button.

   If you are using JDeveloper version 10.1.3 or 10.1.2, Configuration Manager populates the JDeveloper Launch Mapper Classpath field with the appropriate variables for your version of JDeveloper.

   If you are using JDeveloper version 11.1.1 enter the following classpath in the JDeveloper Launch Mapper Classpath field:

   <ORACLE_HOME>\jdeveloper\ide\extensions\oracle.ide.jar; <ORACLE_HOME>\jdeveloper\jdev\extensions\oracle.ide.xmlef.jar; <ORACLE_HOME>\jdeveloper\jdev\extensions\oracle.bpm.mapper.jar; <ORACLE_HOME>\jdeveloper\integration\lib\bpm-ide-common.jar; <ORACLE_HOME>\jdeveloper\ide\lib\javatools.jar; <ORACLE_HOME>\jdeveloper\jdev\lib\xmleditor.jar; <ORACLE_HOME>\oracle_common\modules\oracle.xdk_11.1.0\xmlparserv2.jar; <ORACLE_HOME>\oracle_common\modules\oracle.xmlef_11.1.1\xmlef.jar;C:\JDeveloper11g\oracle_common\modules\oracle.javatools_11.1.1\javatools-nodeps.jar

6. Click the OK button.

You launch Oracle XSL Mapper from within an application engine transform program.

The first time you launch the mapper, the Oracle JDeveloper Welcome window appears.

Image: JDeveloper Welcome window

This example shows the JDeveloper Welcome window.

The Oracle JDeveloper Welcome window displays only the first time you access JDeveloper. When you subsequently open Oracle XSL Mapper, the transform program appears in the Design view.

Image: Oracle XSL Mapper – Design view

This example illustrates the Oracle XSL Mapper – Design view.

The transform program name in the mapper takes the following format:

<transform_program_name>.<section_name>.<step_name>.xsl 

To launch Oracle XSL Mapper:

1. Create a Transform Only application engine program and define the program properties described earlier in this topic.

2. Double-click the XSLT action.

3. Access the Oracle XSL Mapper–Design view.

   When accessing the mapper for the first time, when you double-click the XSLT action and launch Oracle JDeveloper the JDeveloper Welcome window appears. To switch to the Design view, above the Source pane, click the transform file name tab or from the Window menu click the transform file name.

   In subsequent attempts to launch the mapper, double-clicking the XSLT action automatically opens the transform program in the Design view.

This section provides information for access online Help, documentation and other resources for using Oracle XSL Mapper.

This discusses how to:

• Navigate in the Design View.

• Navigate in the Source View.

Navigating in the Design View

To access the Design view of Oracle XSL Mapper, click the Design tab at the bottom of the mapper.

Image: Oracle XSL Mapper – Design view

This example illustrates the fields and controls on the Oracle XSL Mapper – Design view. You can find definitions for the fields and controls later on this page.

Use the Design view to map records and fields.

A few of the key areas of the Design view are discussed here. For additional information on Design view features, see the Oracle XSL Mapper documentation.

Field or Control	Definition
Title Bar	The title bar displays the full path to the Oracle JDeveloper installation location and the name of the current transform program.
Developer Welcome (tab)	Click the tab to display links to online resources, such as documentation, online demos and code samples.
Transform Program name (tab)	Click to access the transform program.
Source	The Source pane in the Oracle XSL Mapper main development view provides a hierarchical view of the source or input message and schema. Click the Expand button (+) button and the Collapse button (-) to expand and collapse data shown. Drag the edges of the pane in or out to adjust the viewing area.
Target	The Target pane in the Oracle XSL Mapper main development view provides a hierarchical view of the target or output message and schema. Click the Expand button (+) button and the Collapse button (-) to expand and collapse data shown. Drag the edges of the pane in or out to adjust the viewing area.
Design (tab)	Located at the bottom left-side of the window, click the tab to display the area where you map records and fields.
Source (tab)	Located at the bottom left-side of the window, click the tab to view and edit the raw XSLT code generated by Oracle XSL Mapper.

Navigating in the Source View

To access the Source view of Oracle XSL Mapper, click the Source tab at the bottom or the mapper.

Image: Oracle XSL Mapper–Source view

This example illustrates the Oracle XSL Mapper–Source view.

Use the Source view to view and edit the raw XSL code generated by the mapper.

For additional information on Source view features, see the Oracle XSL Mapper documentation.

To map records and fields, use the Oracle XSL Mapper – Design view to drag record names and field names from the source pane to the target pane in the mapper.

Image: Oracle XSL Mapper – Design view

This example illustrates the Oracle XSL Mapper – Design view.

A solid green line appears as you drag the cursor from the source pane to the target pane. When you release the cursor, the line turns blue to show the association.

To map records and fields:

1. Open the Design view of Oracle XSL Mapper.

2. Expand the contents of both the source and target panes.

   Click the Expand button (+) to expand each level or section until all records and fields appear.

   Note: When working with rowset-based messages the content to map is located in the MsgData section.

3. In the source pane, click on the icon to the left of a record or field name and drag it to the name of the record or field in the target pane to which you want to map.

   Repeat this step for each record or field to map.

4. Click the Save button.

If you have not saved the program and want to delete the last map you made, simply right click in the Design view and select Undo Link. Otherwise, follow the instructions in this section.

To delete a record or field map:

1. In the source pane, click the record or field name.

2. From the Edit menu, click Delete.

3. Save the changes.

After you have made all of the record and field maps for the program. Click the Source tab at the bottom of the window to generate and view the raw XSL.

You can test XSL maps for validity that you generate in the mapper using the Test XSL Map window. To access the Test XSL Map window, right-click anywhere in the code area and select Test.

Image: Test XSL Map window

This example illustrates the Test XSL Map window.

The code created by the record and field mapping displays in the bottom portion of the window.

To test XSLT code:

1. Access the Oracle XSL Mapper–Source view.

2. Right-click anywhere in the code area and select Test.

   The Test XSL Map window appears.

3. In the XSL Map section of the window, click the Validate button.

   A validation success or error message displays.

If you add code to XSLT that you create using Oracle XSL Mapper that contains any PeopleSoft-related elements it will not compile successfully, unless you create a configuration file of PeopleSoft elements that the mapper should ignore. After you create this file specify the file location and name in the Oracle XSL Mapper Preferences.

<element name = "psft_function">
<element name = "psft_workingstorage">

<?XML version='1.0' encoding='windows-1252'?>
<elements-to-ignore>
     <element name = "psft_function"/>
     <element name = "psft_workingstorage"/>
</elements-to-ignore>

Specifying Elements to Ignore Configuration Files in Oracle XSL Mapper Preferences

Once you create the file of PeopleSoft elements to ignore, enter the file location and name in the mapper Preferences dialog box.

Image: Preferences dialog box

This example illustrates the Preferences dialog box in the Oracle XSL Mapper.

To specify an elements to ignore configuration file in Oracle XSL Mapper preferences:

1. In Oracle XSL Mapper, from the Tools menu, select Preferences.

   The Preferences dialog appears.

2. In the list on the left-side of the window, click XSL Maps.

3. In the Elements to Ignore Conf. File (Requires Restart) field, enter or browse to the location of the elements to ignore configuration file that you created.

4. Click the OK button.

You must restart Oracle JDeveloper for the system to recognize the configuration file.