Rewriting SOAPAction headers with WebSphere DataPower SOA Appliances

When WebSphere DataPower is used to transform a SOAP/HTTP back-end Web service to a different front-end Web service interface, the configuration should transform the HTTP SOAPAction to the correct value expected by the back end. This article describes different solutions for doing this transformation.

Share:

Ali Ahmed El Gamal (elgamal@eg.ibm.com), IT Specialist, IBM

Photo of Ali El GamalAli El Gamal is an IT Specialist at the IBM Technology Development Center in Cairo, Egypt. He received a Bachelor of Science degree in Computer Science at Cairo University in 2006, and a Master of Engineering degree in Software Engineering at Nile University in 2009. He is an IBM Certified Solution Implementer for WebSphere DataPower, an IBM Certified Integration Developer for WebSphere Enterprise Service Bus, an IBM Certified Solution Developer for XML, and a Sun Certified Developer for Java Web Services. You can contact Ali at elgamal@eg.ibm.com.



20 April 2011

Also available in Chinese

Introduction

IBM® WebSphere® DataPower® is often used to transform or adapt a back-end SOAP/HTTP Web service to a different Web service interface. In such scenarios, the mediation logic almost always transforms the SOAP messages. But transforming the SOAPAction header is usually forgotten, which leads to problems later during integration testing. Fortunately, WebSphere DataPower is flexible enough to enable you to easily transform the SOAPAction header, and this article will show you four different ways to do that.

Background

The SOAPAction header is defined as part Web Service Description Language (WSDL) 1.1 specification. Originally, the purpose of this header was to identify the intent of the request -- the operation to be invoked on the back end. Later as part of WS-I Basic Profile V1.1, it was recommended not to depend on it, but some service providers continued to do so. Therefore it is always better when building a mediation layer in front of a SOAP/HTTP Web service to make sure that you correctly rewrite the SOAPAction header as part of your mediation logic.

The soapAction attribute is associated with each operation binding in the WSDL and its value is not necessarily the same as the operation name -- it can be any URI. When the SOAP request is sent over HTTP, an HTTP header named SOAPAction is presented with a value equal to the soapAction attribute of the requested operation, surrounded with double quotes. Listing 1 shows a WSDL snippet with the soapAction attribute defined:

Listing 1. Sample SOAP/HTTP binding with soapAction attribute defined
<wsdl:binding name="MyServiceBinding" type="tns:MyServicePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="operation1">
            <soap:operation soapAction="OP1"/>
                <wsdl:input>
                    <soap:body use="literal"/>
                </wsdl:input>
                <wsdl:output>
                    <soap:body use="literal"/>
                </wsdl:output>
            </wsdl:operation>

SOAPAction Header Value

The request's SOAPAction HTTP header value must be a quoted string equal to the value of the soapAction attribute in the WSDL binding of the operation. If the soapAction attribute in the WSDL is empty, the SOAPAction HTTP header of the request will be an empty string (two double quotes).

When creating a new Web Service Proxy on WebSphere DataPower, one of the proxy settings is the SOAPAction policy, which is highlighted in Figure 1 below and has three options:

  • Lax: Default option. It mandates the SOAPAction header to contain the exact value of the soapAction attribute in the WSDL but it also allows empty SOAPAction values.
  • Off: No check will be performed on the SOAPAction header.
  • Strict: The SOAPAction header must match the soapAction attribute in the WSDL, or else the request is not permitted.
Figure 1. SOAPAction policy in the proxy settings
SOAPAction policy in the proxy settings

This policy affects the service that is exposed by WebSphere DataPower, not the back-end Web service. The service configuration needs to transform the incoming SOAPAction HTTP header to the value expected by the back-end Web service. The following sections describe different ways to do that.

Solution 1. Using an XSL file

In this solution, you develop an XSL file that uses an extension element called set-http-request-header. This element has two attributes:

  • Name: Header name that you want to set. In this use case, set it to SOAPAction.
  • Value: Header value to set. It should be the SOAPAction header value for the back-end service.

Here is an example of using this element:

Listing 2. XSLT to rewrite the HTTP SOAPAction header
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:dp="http://www.datapower.com/extensions" 
    xmlns:dpconfig="http://www.datapower.com/param/config"
    extension-element-prefixes="dp" 
    exclude-result-prefixes="dp dpconfig">

    <xsl:param name="dpconfig:SOAPAction" />
    <dp:param name="dpconfig:SOAPAction">
        <display>SOAPAction header value</display>
    </dp:param>

    <xsl:template match="/">
        <xsl:copy-of select="/*"/>
        <dp:set-http-request-header name="'SOAPAction'" 
            value="$dpconfig:SOAPAction"/>
    </xsl:template>

</xsl:stylesheet>

The XSL file above takes the SOAPAction header value as a parameter, so when you configure the transform action, open the Advanced tab, set the SOAPAction header value field, and click Save:

Figure 2. Configuring the SOAPAction header value parameter in the Transform action
Configuring the SOAPAction header value parameter in the Transform action

This action should be configured in the request rule of your processing policy. In this solution, you may not need to use the exact code shown in Listing 2 above. Specially, if you are going to use one XSL file to set the SOAPAction header depending on which Web service operation is being invoked.

Solution 2. Using a header rewrite action

In this solution, rewrite the SOAPAction header using one of the advanced actions called Header Rewrite. When configuring the request processing rule:

  1. Drag the Advanced action icon:
  2. Select Header Rewrite from the list.
  3. Create a new URL Rewrite Policy.
  4. Type a name for the policy and select URL Rewrite Direction to Request:
    Figure 3. Configuring header rewrite policy 1
    Configuring header rewrite policy 1
  5. Open the URL Rewrite Rule tab and click Add. Fill in the values shown in Figure 4 below and then click Apply:
    Figure 4. Adding a new URL rewrite rule
    Adding a new URL rewrite rule
    • URL Rewrite Type: The type of URL rewrite rule. header-rewrite indicates that a request header will be rewritten.
    • Match Expression: Perl-compatible regular expression that matches against the value of the header. In Figure 4, .* means that the rule matches any value for the SOAPAction Header.
    • Input Replace Expression: Value of the header after the rule is executed.
  6. Apply and save all changes.

In this solution, you can create multiple URL-rewrite rules, each one responsible for transforming the SOAPAction header for a different operation. Obviously, you will need to change the match expression for the rules to be more specific that the one described in Figure 4 above.

Solution 3. Using Web service proxy header injection

In this solution, you don't touch the processing policy. Instead, you configure the SOAPAction header rewrite on the Web service proxy level. Use the following steps:

  1. Open you Web service proxy from the Control Panel home page.
  2. Open the Headers/Params Tab.
  3. Under Header Injection Parameters, click Add.
  4. Fill in the values as shown below and click Submit:
    Figure 5. Configuring SOAPAction header injection on a Web service proxy
    Configuring SOAPAction header injection on a Web service proxy
    • Direction indicates when the header should be injected.
    • Back means that the header will be injected when the message travels from the Web service proxy to the back-end service.
  5. Click Apply and save the changes.

Solution 4. Using the user agent

In this solution you don't touch the Web service proxy configuration, but you configure the user agent object of the XML manager, which is referenced by the Web service proxy.

  1. Open the User Agent object. If you don't know the user agent associated with your Web service proxy, open the Proxy Settings Tab of your Web service proxy, click the button next to XML Manager, and then click the button next to the User Agent Configuration.
  2. Open the Soap-Action Policy tab.
  3. Click Add.
  4. In the URL Matching Expression field, type the back-end service URL. In the SOAP Action field, type the SOAPAction header value.
  5. Click Apply and save the changes.

Modifying the user agent or the XML manager named default is not recommended because these are used for new services and some existing services may be using them as well. Instead, create a new user agent object and/or an XML manager object before applying the steps above to it.

Conclusion

This article explained several ways to rewrite the SOAPAction header using WebSphere DataPower. It explained that the SOAPAction header is associated with a Web service operation, and not a Web service interface. Solution 3 inserts the SOAPAction headers into all requests passing through the Web service proxy to the back end. Therefore, if the WSDL that is exposed by the Web service proxy has multiple operations, this solution may not be the best fit. A similar rationale applies to Solution 4 -- if the service back end exposes more than one operation, it may not be the best fit.

Solution 1 and Solution 2 are flexible and don't suffer from SOAPAction header scope like Solutions 3 and 4. Solution 2 is handled through the Web configuration, and doesn't require any XSLT development. However, if you are not comfortable with regular expressions, then Solution 1 is probably a better fit.

Acknowledgements

The author would like to thank Karim Ouda and Mohab El Hilaly for their work reviewing this article.

Resources

  • Industry standards
  • WebSphere DataPower resources
    • WebSphere DataPower documentation
      Complete documentation for the DataPower XA35, XS40, XI50, XB60, and XM70 Appliances.
    • WebSphere DataPower information center
      A single Web portal to all WebSphere DataPower documentation, with conceptual, task, and reference information on installing, configuring, and using the various WebSphere Appliances.
    • WebSphere DataPower developer resources page
      Technical resources to help you use WebSphere DataPower SOA Appliances to simplify, secure, and accelerate XML and Web services deployments within an SOA.
    • WebSphere DataPower product page
      Product descriptions, product news, training information, support information, and more.
    • WebSphere DataPower product library
      Product announcements, case studies, white papers, and more.
    • WebSphere DataPower support
      A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
    • WebSphere DataPower forum
      Get answers to your technical questions and share your expertise with other WebSphere DataPower users.
    • WebSphere DataPower Appliances Handbook
      This retail book shows you how to use DataPower Appliances from the network, security, and ESB perspectives. The book describes installation, configuration, management, monitoring, configuration, build, deployment, DataPower as a network device, and DataPower services, especially the "big three" of XML Firewall, Web Service Proxy, and Multi-Protocol Gateway.
    • IBM Redbook: WebSphere DataPower Appliances, Part I: Overview and getting started
      DataPower SOA appliances are purpose-built, easy-to-deploy network devices that simplify, secure, and accelerate your XML and Web services deployments while extending your SOA infrastructure. This IBM Redbook describes DataPower architecture, use cases, deployment scenarios, and implementation details, as well as best practices for SOA message-oriented architecture in a production ESB environment.
  • WebSphere resources
    • developerWorks WebSphere developer resources
      Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
    • developerWorks WebSphere application connectivity developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
    • developerWorks WebSphere SOA and Web services developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
    • Most popular WebSphere trial downloads
      No-charge trial downloads for key WebSphere products.
    • WebSphere forums
      Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
    • WebSphere on-demand demos
      Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
    • developerWorks WebSphere weekly newsletter
      The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
    • WebSphere-related books from IBM Press
      Convenient online ordering through Barnes & Noble.
    • WebSphere-related events
      Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  • developerWorks resources
    • Trial downloads for IBM software products
      No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
    • developerWorks blogs
      Join a conversation with developerWorks users and authors, and IBM editors and developers.
    • developerWorks Webcasts
      Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
    • developerWorks podcasts
      Listen to interesting and offbeat interviews and discussions with software innovators.
    • IBM Education Assistant
      A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=647426
ArticleTitle=Rewriting SOAPAction headers with WebSphere DataPower SOA Appliances
publish-date=04202011