Overriding the WebSphere DataPower WSDL optimization conversion


IBM WebSphere DataPower SOA Appliance (hereafter called DataPower) helps you virtualize your web services to act as a gateway. This pattern gives you many advantages, such as:

  • Web services virtualization
  • Attack protection
  • Policy enforcement

For this reason, it is common to see this pattern in the network infrastructure of the customers.

Prerequisites and system requirements

This article is written for WebSphere DataPower SOA Appliances administrators and developers who have had interoperability issues with web services consumers that require the schema to be embedded in the WSDL, instead of a reference to the XSD schema file.

To build and execute the example in this article, you will need:

  • A WebSphere DataPower SOA Appliance. While this article is developed using an XI50 device, other models are also compatible, such as XS40, XG45, XI52, XB60, and XB62.
  • An XML editor. You can also use your favorite editor.

Sample files

You can import the export package, provided with this article, from the Import configuration option of your DataPower Control Panel. You will also need to modify the mappings.xml file to make the sample work properly with your services. No further downloads are required to complete the instructions in this article.

Understanding the architecture

One of the typical scenarios where DataPower fits is shown in Figure 1.

Figure 1. Basic scheme of the example
Basic scheme of the example
Basic scheme of the example

The web service itself is located in WebSphere Application Server (hereafter called Application Server) and DataPower sits between Application Server and clients (typically the Demilitarized Zone - DMZ). When a client wants to consume a web service, it invokes to DataPower, which checks for security threats and URL rewrites, checks the scheme of the incoming message, and performs all the operations specified on its processing policy before it invokes the service in the local Intranet.

The most flexible way to expose web services when you work with DataPower is using a Web Service Proxy. When you expose a web service using the Web Service Proxy object, DataPower requires the Web Services Description Language (WSDL) file. Once the service is deployed in the Web Service Proxy, DataPower internally optimizes the WSDL file for its consumption. If a client invokes the address of the service deployed in DataPower (plus the WSDL), it serves an optimized version of the WSDL, as shown in the xsd:import below:

<wsdl:definitions xmlns:wsdl="" ...>
  <wsdl:types xmlns:xsd="">
      <xsd:import schemaLocation="TemperatureConverter.xsd1.xsd" 

Sometimes, a legacy web service client may request the WSDL to the device. As mentioned before, DataPower serves the WSDL with internal references to XML schemas (also known as XSD), and the client cannot retrieve the XSD file. It needs a single WSDL file with every artifact embedded in it.

Therefore, if the client cannot retrieve the schemas, you can configure a Multi-Protocol Gateway in DataPower to retrieve the internal references, compose a single WSDL file, and serve it to the client. This pattern is reflected in Figure 2.

Figure 2. Internal objects involved in the example
Internal objects involved in the example

Creating the Multi-Protocol Gateway in DataPower

  1. Once you are logged into your domain in DataPower, you see the Control Panel page. Click on the Multi-Protocol Gateway icon, and create a new one by clicking on the Add button as shown in Figure 3.
    Figure 3. Adding a new Multi-Protocol Gateway
    Adding a new Multi-Protocol Gateway
    Adding a new Multi-Protocol Gateway
  2. Write a name for the Multi-Protocol Gateway, such as Rewrite_XSD_Imports. Configure it as a dynamic-backend gateway and set both the request and response type as XML.
  3. Add a Front Side Protocol Handler (typically HTTP), and remember to check the GET method under the "Allowed Methods and versions" section, as shown in Figure 4.
    Figure 4. Creating an HTTP Front Side Handler
    Creating an HTTP Front Side Handler
    Creating an HTTP Front Side Handler
  4. Under the Advanced tab, make sure that the Process messages whose body is empty is set to on. This parameter lets DataPower process the GET requests from the clients requesting the WSDL.

Creating the Multi-Protocol Gateway Policy

In this section, you create a policy with three rules in it:

  1. The first rule is in charge of getting all the WSDL requests from the clients, getting the WSDL from the backend, transforming it adding the XSDs, and giving it back to the client.
  2. The second rule bypasses the SOAP request to the backend.
  3. The third rule gets back the response from the backend server and serves it to the client.

The policy looks similar to Figure 5.

Figure 5. Policy overview of the Multi-Protocol Gateway
Policy overview of the Multi-Protocol Gateway
Policy overview of the Multi-Protocol Gateway

Rule 1: Both directions

This rule is triggered when the consumer requests the WSDL (see Figure 6). It will be detected by the presence of the "?WSDL" pattern ending the URL.

Figure 6. Rule overview for the WSDL transformation
Rule overview for the WSDL transformation
Rule overview for the WSDL transformation
  1. Create a match action, which will trigger this rule for every incoming request whose URL ends in "?WSDL". The easiest way to do this is to configure the Match Regular Expression as (.*)[w|W][s|S][d|D][l|L]. Check the Match with PCRE toggle to on under the Main tab of the Matching Rule.
  2. Add a Transform Action after the Match Action you created before, and select the wsdl-fetch.xsl stylesheet of this example.

    This stylesheet gets the WSDL file from the backend. Since the Multi-Protocol Gateway you are creating in this sample can be used to modify the WSDLs of several Web Service Proxy services, the stylesheet loads a routing file, whose format is: URL of the service (deployed in the Multi-Protocol Gateway) and host of the service (where the service is located, typically the Web Service Proxy. An entry for this file would be:

    <mapping source=""

    After getting the host where the service is deployed and building a valid URL for the WSDL, the stylesheet performs a dp:url-open() call to obtain the WSDL. The code for the stylesheet is shown in Listing 1.

    Listing 1. wsdl-fetch.xsl file
    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl=""
        extension-element-prefixes="dp dpconfig regexp"
      <xsl:param name="dpconfig:mapping-file" select="'off'"/>
      <dp:param name="dpconfig:mapping-file" type="'dmFileToggle'" xmlns="">
        <display>Mapping file</display>
        <description>Select the mapping file to convert the URL's
        The default is local:///mappings.xml.</description>
      <xsl:template match="/">
         <xsl:variable name="mappings" select="document($dpconfig:mapping-file)"/>
         <xsl:variable name="host_to_find"
         <xsl:variable name="host"
         <dp:set-variable name="'var://context/wsdl-fetch/host_to_find'"
         <dp:set-variable name="'var://context/wsdl-fetch/host'" value="$host"/>
         <dp:set-variable name="'var://context/wsdl-fetch/wsdl-location'"
         <dp:url-open target="{

    The WSDL is the output of the stylesheet.

  3. Add another Transform Action by selecting the schema-fetch.xsl sytelesheet from the sample code.

    The schema-fetch.xsl stylesheet finds all the imports in the previously downloaded WSDL and replaces all of them with the document, which it is pointing to. To replace the import tags, the stylesheet builds, again, the URL of each schema and uses the dp:url-open() extension again to fetch them and place it into the WSDL file. The code for the schema-fetch.xsl stylesheet is shown in Listing 2.

    Listing 2. schema-fetch.xsl file
    	<?xml version="1.0" encoding="UTF-8"?>
    	<xsl:stylesheet xmlns:xsl=""
    	    extension-element-prefixes="dp regexp"
    	    <xsl:template match="/">
    	    <xsl:template match="/*[local-name()='definitions']
    	        <xsl:for-each select="*[local-name()='import']">
    	              <xsl:variable name="myURI"
    	              <xsl:variable name="location"
    	              <dp:url-open target="{$location}"/>
    	    <!-- Copy everything else -->
    	    <xsl:template match="@*">
    	    <xsl:template match="*">
    	            <xsl:copy-of select="@*"/>
    	            <xsl:apply-templates select="node()"/>
  4. After the second transformation, add a set-variable action and set the var://service/mpgw/skip-backside variable to "1". This avoids the backside processing phase.

Rule 2: Client-to-server direction

This rule handles the client SOAP requests and forwards it to the backend (see Figure 7).

Figure 7. Rule overview for the SOAP requests
Rule overview for the SOAP requests
Rule overview for the SOAP requests
  1. Create a match-all action that gets all the SOAP requests and sends them to the backend.
  2. Add a transform action after the match-all and select the wsdl-post.xsl stylesheet provided in the sample file. This stylesheet gets the routing information (as you previously did in the first rule) and forwards the SOAP request to the backend. The content for the wsdl-post.xsl stylesheet is shown in Listing 3.
    Listing 3. wsdl-post.xsl file
    	<?xml version="1.0" encoding="UTF-8"?>
    	<xsl:stylesheet xmlns:xsl=""
    	    <xsl:template match="/">
    	        <xsl:variable name="mappings" select="document('local:///mappings.xml')"/>
    	        <xsl:variable name="host" select="$mappings/mappings/mapping[@source=
    	        <dp:set-variable name="'var://service/routing-url'" value="concat(

Rule 3: Server-to-client direction

This rule handles the SOAP response and serves it back to the consumer (see Figure 8).

Figure 8. Rule overview for the SOAP responses
Rule overview for the SOAP responses
Rule overview for the SOAP responses

Create a server-to-client rule just to get the SOAP responses back to the client.

Sample files

The zip file provided with this article contains the sample files you previously selected in the configuration of the Multi-Protocol Gateway. Unzip them using your favorite ZIP extraction tool. An export of the Multi-Protocol Gateway is also provided (, so you can import it using the Import Configuration option in the DataPower Control Panel. The zip file includes the following files:

  • mappings.xml
  • schema-fetch.xsl
  • wsdl-fetch.xsl
  • wsdl-post.xsl


In this article, you learned how to change services in WebSphere DataPower to modify the content of the WSDL files served by the Web Service Proxy object, or any other server that splits the WSDL file in several files. Splitting the files is good practice, but some clients are not able to get those files. You also learned how to route requests using a routing file and the var://service/routing-url variable.

Downloadable resources

Related topics

  • WebSphere DataPower V4.0.1 Training: In this IBM Training course, you learn about the components of the WebSphere DataPower. The course also explores patterns, common security threats, and shows you how to build services to interoperate with various systems.
  • WebSphere DataPower V4.0.2 Information Center: A single web portal to all WebSphere DataPower documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere DataPower SOA Appliance.
  • WebSphere DataPower Education Assistant: A web portal to WebSphere DataPower documentation, with narrated presentations given by people from education and people from the labs.
  • developerWorks WebSphere DataPower zone: A technical resources page that provides how-to articles and information about DataPower.


Sign in or register to add and subscribe to comments.

ArticleTitle=Overriding the WebSphere DataPower WSDL optimization conversion