XSLT Converter

Usage

Using the XSLT Converter, you can transform an XML format to any other file format. The transformation the XSLT Converter uses one or more XSLT stylesheets including instructions on how to transform the content of the XML files.

An XSLT processor supports you in the following tasks:

  • Transform file formats, e.g., from one XML format to another XML format.

  • Create messages by using templates for System Connectors, e.g.:

    Web Services Connector, Topcall Connector, SAP Connector, JCA Connector, Database Connector.

  • Create messages by using templates from the repository.

XSL versions and EXSL support

The range of languages available to you in the XSLT converter depends on the XSL processor you are using. The supplied XSLT processor supports the following functions:

  • XSLT 1.0 (deprecated, not recommended, not supported as of INUBIT 8)

  • XSLT 2.0

  • XSLT 3.0

  • EXSLT

    • common

    • sets

    • math

    • dates-and-times

    • random

  • INUBIT XSLT Extensions including functions

    • For date conversion

    • For returning line feeds and other control characters

    • For creating tags

    • For replacing umlauts

You can replace the supplied XSLT processors by any other XSLT processor, if needed.

In XSL transformations using the Saxon 10 XSL processor and the output method XHTML unwanted line feeds might occur in the resulting XHTML output.

<xsl:output method="xhtml" [..] />

To avoid line feeds, it is recommended to add the attribute indent set to no:

<xsl:output indent="no" method="xhtml" [..] />

Refer to your XSLT processor’s documentation for information about its extensions.

The XSLT converter removes the CR from the CRLF combination when parsing the input message. This is due to `dom4j.jar’s internal parsing process, which is recommended by W3C.

Refer to

XSLT Mapper User Interface

XSLT Mapper

The XSLT Mapper is displayed after an XSLT Converter module is created:

module guide 882 0

  1. XML source/XML target (stylesheet area)

    The stylesheet pane displays the created XSLT stylesheet as mapping table. The table columns include:

    • XML source: Values, XPath expressions or functions, usually dragged and dropped from the XML source file pane.

    • XML target: XSLT commands (elements and attributes), usually dragged and dropped from the pane Target structure.

    • Add Parameters: To merge the parameters from the imported stylesheet to the existing stylesheet , click on Add Parameters.

      For information about the pane toolbar refer to Toolbar Functions in the XSLT Converter.

  2. module guide 882 2 Icon to open the XPath assistant

    Refer to XPath Assistant

  3. XML source file

    For loading and displaying an example input message, which serves as data source for creating the XSLT stylesheet. This pane is hidden if you selected the Ignore input message checkbox when you created the XSLT Converter. For information about the pane toolbar refer to Toolbar Functions in the XSLT Converter.

  4. Target structure

    For loading and displaying of a template for the target structure. Any example file or template from the repository can serve as template. A template can be created by using any explorer, e.g. SAP explorer, database explorer or Web service explorer.

  5. Mapping results

    Displays the result after having tested the XSLT stylesheet and the amount of run time needed.

    For information about the pane toolbar refer to Toolbar Functions in the XSLT Converter.

  6. Output, Breakpoints, Internal

    To display the style sheet output, breakpoints defined, and the style sheet structure.

Toolbar Functions in the XSLT Converter

Each pane has a toolbar that gives you access to the following functions:

  • module guide 883 1: Opens a menu with the following commands:

    • New: Deletes the current content and creates a new document with a root element.

    • Open: For loading files from the file system, the Repository or content from the clipboard. The editor automatically loads the view that matches the file type. Additionally, used to load Business Object Diagrams or URLs or templates from the following explorers:

    • Save:

      • File: For saving the displayed content.

      • File as: Opens the file explorer for saving the displayed content to any location.

      • Repository: For saving the displayed content to the repository.

      • Clipboard: Copies the displayed content to the clipboard.

    • Print: Opens the printer dialog for printing the current file.

      The following functions are not necessarily available in all areas!

    • Display appropriate editors for the content: Reduces the number of available editors to those which are appropriate for the currently displayed file format.

    • Generate XML schema template:

      Creates on the basis of an XML file a template for an XML schema.

      Refer to Generating an XML Schema template from an XML file

    • Compare

      Compares an XML file with a file in the file system, a file in the repository or with the content of the clipboard.

      Refer to Comparing XML documents

    • XPath search: If checked, the text in the search field is interpreted and searched for as an XPath expression.

      Refer to Searching with XPath expressions

    • Editable (source and target areas only): Edits existing files and creates new files.

    • Parameters from clipboard (only in XSLT script pane): Copies variables from the clipboard to the XSLT script.

    • Adjust toolbar to content: Based on the format of the current content, the appropriate commands for the pane are enabled. For ASCII text files, for instance, Schema view and Tree view will not be available.

    • Only distinct nodes (not in the XSLT script pane): Hides all duplicate elements.

    • Remove data from structure (only in target pane): Deletes all content that is neither an element nor an attribute.

    • Remove only text nodes from structure (only in target pane): Deletes all contents of element . Attribute values remain unchanged.

    • Remove only attribute texts from structure (only in target pane): Deletes all attribute values. Element contents remain unchanged.

    • Check result file with DTD: Validates the result file against a DTD.

    • Check result file with schema: Validates the result file against an XML schema.

  • module guide 884 1 XSLT mapping table A view for creating XSLT scripts by dragging and dropping. This mode is automatically displayed after you have created an XSLT Converter module.

    • Left: XPath expressions and values display

    • Right: Elements and attributes

      For color settings:

      Refer to Changing INUBIT Workbench Settings

    • Middle column:

      • Cell containing an equal sign: One attribute (right column) is assigned one value (left column).

      • Cell containing an arrow: Indicates that one element (right column) is assigned one XPath expression (left column).

        By clicking the icon, you open the XSLT command wizard.

        Refer to XSLT Command Wizard

  • module guide 884 2 Schema view

    Use this view to edit a schema (only available if a schema has been loaded).

    Refer to Schema Editor

  • module guide 884 3 Tree view

  • module guide 884 4 Text view

    Displays file elements as text.

  • module guide 884 5 Open external editor

    Displays a list of all application profiles that can be used to open the file.

  • module guide 884 6 Search

    Refer to Tab-wise Search

Other Functions in the XSLT Converter

Drag’n’Drop

The XSLT Mapper offers the following options for creating elements, XPath expressions or structures by using Drag’n’Drop:

The area where you want to create something must be editable. From the toolbar, select module guide 884 7 > Editable.

  • Drag-and-Drop to copy elements between any of the three panes

  • Copy elements within a single pane: Hold the Control key while dragging and dropping.

  • Create new source and target structure

    1. From the toolbar, select module guide 885 0 > New > <type_of_the_new_file>.

    2. Drag an element in the area.

  • Create XPath specifications by dragging and dropping: Drag elements from the source file to the left side of the XSLT script pane.

Context menus

If you right-click a selected element in the script pane or in the XML source and target files, a context menu is displayed, showing commands relevant to the selection.

Command Note

Copy

Align text

Only available in text views Modifies the document

Cut

Paste

Move node – to the left

Select node first

Move node – to the right

Select node first

Move node – up

Select node first

Move node – down

Select node first

Collapse node

Select node first

Expand node

Select node first

Expand all subordinate nodes

Select node first

Open input field for search

Open menu below arrow

To close the menu without selecting a command, press the Escape key.

Find used nodes in source document

When you select an element in the mapping table and enable this option, all nodes in the XML source file that are used for the script element are selected. If no node is found in the XML source file, a warning signal will sound.

XSLT command wizard

Opens the XSLT command wizard

Refer to XSLT Command Wizard

Testing XSLT file

You can test your XSLT style sheet while creating it.

Keys and their functions

Key Function

Del(ete)

Deletes the selected element or attribute

Home, End, Page up, Page down

To navigate within the stylesheet

Enter

Navigates one line down

Shift Enter

Navigates one line up

Shift module guide 886 1,

Shift module guide 886 2

Marks the current and the following line(s)

Tabulator

Switches between XML source and XML target

Ins(ert) and all the other keys not mentioned here

Switching to edit mode for the element/attribute selected

XSLT – Oracle Database Explorer

In databases such as PostgreSQL, MySQL, MSsql, MariaDB, and DB2, a single user can have multiple schemas, and they can see multiple schema table details.

However, because a user in Oracle has only one schema, the appropriate permissions must be granted for that user to access the schemas of other users.

Proceed as follows

  • In the XSLT converter, go to menu and select Open > Database Explorer. The dialog Database Explorer is displayed.

  • Select Module. The schema name and SQL statement will be loaded.

  • Select Schema name. The appropriate SQL statement and tables are loaded.

Both, the person who grants access and the person who receives it must have all the privileges.

Run the below query:

GRANT ALL PRIVILEGES TO <username>;

GRANT SELECT ANY DICTIONARY TO <username>

XSLT Command Wizard

Call Up

Do one of the following in the Stylesheet area:

  • select an element in the right column > context menu > XSLT command wizard

  • click module guide 886 3 or module guide 886 4 in the table’s center column.

You cannot call up the wizard in cells containing an equal sign (attribute with value assignment)!
module guide 887 0

The XSLT command wizard provides information about the XSLT element which is selected in the Script area and inserts elements and attributes at the selected position.

The XSLT command wizard includes the following panes:

  1. Element list

    Optionally XSLT 1.0 (deprecated), 2.0, or 3.0.

  2. Element Descriptions

    For the element selected in the list.

  3. Attribute Descriptions

    For the attribute selected in the attribute table.

  4. Attribute table

    Displays all attributes and the values of the selected element.

    • Black font: Mandatory attributes.

    • Grey Font: Optional attributes.

      The value ranges of attributes are displayed as tool tips above the value fields. To assign a value to an attribute, click the Value field and enter the value.

      If the select attribute exists for an XSLT command you can open the XPath assistant by clicking the module guide 887 1 button.

  5. Position of an XSLT element

    • Precede: The command is placed in the hierarchical level where the selected element was located. The element is indented below it.

    • Replace: Replaces the existing XSLT command with the selected command.

    • Append: The command is added below the currently selected element (one level lower in the hierarchy).

Ensuring Saxon 10 compatibility

Action

Migrate existing XSLT Stylesheets if XSLT scripts are failing or to ensure full Saxon 10 compatibility.

Proceed as follows

  • Go to Module Editor tab

  • Select Data Converter > XSLT Converter in the module tree

  • Open context menu and select Migrate to Saxon 10

  • Go to Repository tab

  • Select Repository table

  • Open context menu and select Migrate to Saxon 10

Testing the XSLT Stylesheet in the XSLT Converter

You can test your XSLT stylesheet while you are creating it.

Proceed as follows

Do one of the following:

  • Select Edit > Test XSLT file.

  • Click the module guide 888 0 button in the toolbar.

The result and the execution time required are displayed in the XML target file area in the Mapping results tab.

Validating the Result

You have the following options for validating a mapping:

  • Check result file against DTD

    Go to Edit > Check result file with DTD.

    You can also start this check in the toolbar of the Mapping results pane (sub menu Check result file with DTD).

    Refer to Toolbar Functions in the XSLT Converter

  • Check result file against schema

    Go to Edit > Check result file with schema.

    You can also start this check in the toolbar of the Mapping results pane (sub menu Check result file with schema).

    Refer to Toolbar Functions in the XSLT Converter

The path to the DTD resp. the XML schema must either be specified in the XSLT stylesheet, or the system will prompt you to open a matching file.

The validation result is displayed in a dialog. Any errors detected are specified in detail, enabling you to change your mapping accordingly.

Using Extensions and Java Packages

Overview

In order to implement features in an XSLT stylesheet, which are not covered by the XSLT commands, you can use extensions or functions from Java packages.

Using Extensions

For extensions ready for use refer to

Once you use processor specific extensions, your XSLT stylesheet becomes dependent on the selected processor! If you change the processor afterwards, your stylesheet might not run any longer.

Proceed as follows

  1. Display your XSLT stylesheet.

  2. Add a namespace attribute to the xsl:stylesheet element via the context menu, e.g.:

    <xsl:stylesheet xmlns:string="http://exslt.org/string" />

  3. Add the extension-element-prefixes attribute and enter the prefix of the extension as value, e.g.: extension-element-prefixes="string"

Calling up extensions

An extension is called via its defined prefix and its name, e.g.:

<xsl:template match="/">
  <tokens>
    <xsl:for-each select="string:tokenize('A,B,C,D,' , ',' )">
      <xsl:copy-of select="."/>
    </xsl:for-each>
  </tokens>
</xsl:template>

Embedding Java Packages of the INUBIT Software

Prerequisites

You installed the SDK with INUBIT software.

For a description of the extensions provided with the INUBIT Process Engine open the following link: <inubit-installdir>/inubit/documentation/apidoc/index.html.

Package: com.inubit.ibis.xsltext

Class: Formatter and Misc

Proceed as follows

  1. Display your XSLT stylesheet.

  2. Add a namespace attribute to the xsl:stylesheet element via the context menu. As value enter the package name, e.g.:

<xsl:stylesheet xmlns:Formatter="java:com.inubit.ibis.xsltext.Formatter"/>

Calling functions from the package

A method from a package is called via its prefix and name:

<xsl:template match="/">
  <DateTime>
    <xsl:value-of select="Formatter:getDateTime('yyyyMMddHHmmss')" />
  </DateTime>
</xsl:template>

Embedding Any XSLT Processor

Common uses include the Xalan and SAXON processors, which are included in the system.

In addition to the XSLT processors included, you can use any other XSLT processor. You will need a JAR file with the XSLT processor, which must correspond to the specified Java interface.

Proceed as follows

  1. In the INUBIT Workbench, display the Administration tab.

  2. To load the JAR file to the server, select from the burger menu Configuration > Library Manager…​.

    A dialog opens. For further steps refer to Managing Libraries.

    Before uploading the JAR file, select the Driver library in the Library type section.

  3. Open your XSLT converter’s properties for editing or create a new module.

  4. Enter the new XSLT processor’s class name in the XSLT processor field.

    Refer to Dialog XSLT Converter Properties

  5. Click Finish.

→ You can now use the new XSLT processor.

Using Variables

You can easily access variables in the XSLT Converter, for instance to send comprehensible error messages to an error branch.

When using base64Binary type variables in XSLT Converters of INUBIT versions 5.1 or older: In these XSLT Converters, the variables content was output in compressed form. In this case, you must use the XPath function misc:decodeWithDecompression($variable) for decoding the content of the variable. Alternatively, you can create a new XSLT Converter. In doing this, you get the uncompressed content of the variable.

Proceed as follows

  1. Create an XSL Converter module, and integrate it into a Technical Workflow.

  2. Test the Technical Workflow.

  3. Double-click the watch point before the XSLT Converter module. A dialog opens, displaying the result file with the existing variables.

  4. To copy the result file and the variables to the clipboard, click Copy data. Close the dialog.

  5. Open the XSLT Converter module for editing.

  6. In the XSLT script area, open the menu (module guide 891 1) and select Parameters from clipboard. A window in which you can select a variable opens.

  7. Select a variable and click OK.

The dialog will close. A parameter with the same name as the variable is created and displayed in the script pane:

module guide 891 2

Refer to

Dialog XSLT Converter Properties

Transformer properties

  • XSLT processor

    Selects an XSLT processor. XSLT processors differ in terms of the language scope they support.

  • Processor attributes

    Enter properties with values for the XSLT processor in this table. The properties are implementation-specific transformer factory attributes.

Mapper properties

  • Save source- and target files on the Process Engine

    If checked, source and target files are stored on the INUBIT Process Engine. Thus, these files can also be edited on other client machines.

    If the source and target files are very large, the performance can be affected, because these files are loaded each time the XSLT Converter is executed.

    If you have already published the XSLT Converter at and deselect the option later on, the files on the INUBIT Process Engine and the reference to the local copy on the client machine are deleted.

  • Ignore input message

    When selected, the pane XML source file is hidden from the XSLT Mapper user interface. Ignoring the input message can be helpful when using one or more XSLT stylesheets for recreating a structured output message.

  • Cache the XSLT stylesheet

    If the XSLT converter is called up several times in short succession, caching the script will increase performance.

    The module in the cache is updated during server start and during module publishing.

    Refer to Embedding Any XSLT Processor

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen