WebSphere DataPower SOA Appliances

Integrating with WebSphere Transformation Extender

WebSphere DataPower SOA Appliances

Integrating with WebSphere Transformation Extender

Note Before using this information and the product it supports, read the information in Appendix C, Notices and trademarks, on page 17.

First Edition (January 2009) This edition applies to the following releases and to all subsequent releases and modifications until otherwise indicated in new editions: v Version 3, release 7, modification 2 of IBM WebSphere DataPower XML Security Gateway XS40 v Version 3, release 7, modification 2 of IBM WebSphere DataPower XML Integration Appliance XI50 v Version 1, release 0, modification 0 of IBM WebSphere DataPower B2B Appliance XB60 v Version 1, release 0, modification 0 of IBM WebSphere DataPower Low Latency Messaging Appliance XM70 Copyright International Business Machines Corporation 2006, 2009. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Preface . . . . . . . . . . . . . . . v
Who should read this document . . . . . . . . v How this document is organized . . . . . . . v Publications . . . . . . . . . . . . . . v Installation and upgrade documentation . . . . v Administration documentation . . . . . . . vi Development documentation. . . . . . . . vi Reference documentation. . . . . . . . . vii Integration documentation . . . . . . . . vii Problem determination documentation . . . . vii Supplemental documentations . . . . . . . vii Typeface conventions . . . . . . . . . . . viii Creating cryptographic material for the HTTPS service . . . . . . . . . . . . . . . 7 Importing the test domain . . . . . . . . . 8 Testing the tx-test XML Firewall service . . . . 8 Developing and testing maps in Design Studio . . . 9 Uploading the map files to the DataPower appliance 10 Defining a WTX transform action in DataPower . . 10 Defining a single input and output . . . . . 11 Defining multiple inputs and outputs. . . . . 11

Appendix A. Migrating to DPA mode . . 13

Converting .mms and .mtt files . Converting .xml and .mts files . . . . . . . . . . . . . . 13 . 13

Chapter 1. Overview . . . . . . . . . 1
Software requirements . . . . . . . Compatibility with existing maps . . . Limitations and restrictions . . . . . DPA Mode . . . . . . . . . . Exported Files Mode and Exported Files Mapping Logic Disabled Mode . . . . . . . . . . . . . . . . . . . . . . 1 2 2 3

Appendix B. Getting help and technical assistance . . . . . . . . . . . . . 15

Searching knowledge bases . Getting a fix . . . . . . Contacting IBM Support . . . . . . . . . . . . . . . . . . . . . . . . 15 . 15 . 16

. 4

Chapter 2. Steps for developing and deploying maps . . . . . . . . . . . 7

Configuring Design Studio . . . . Configuring the DataPower appliance . . . . . . . . . . 7 . 7

Appendix C. Notices and trademarks

Trademarks . . . . . . . . . . . . .

17
. 17

Index . . . . . . . . . . . . . . . 19

Copyright IBM Corp. 2006, 2009

iii

iv

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Preface
IBM WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy Network appliances that simplify, help secure, and accelerate your XML and Web Services deployments while extending your SOA infrastructure. These appliances offer an innovative, pragmatic approach to harness the power of SOA while simultaneously enabling you to leverage the value of your existing application, security, and Networking infrastructure investments.

Who should read this document

This document is intended for developers who will use WebSphere Transformation Extender (WTX) Design Studio to create transformation maps to be used by an IBM DataPower appliance to transform message data from binary to XML.

How this document is organized

This document has the following organization: v Chapter 1, Overview Provides an overview of how to use WebSphere Transformation Extender (WTX) Design Studio to perform design-time functions, including create transformation maps to be used by an IBM DataPower appliance to transform message data from binary to XML. v Chapter 2, Steps for developing and deploying maps Provides procedures for developing maps in Design Studio, deploying maps to the DataPower appliance, and creating transform actions for DataPower services that use maps. v Appendix A, Migrating to DPA mode Provides migration procedures to upgrade existing maps that use deprecated map modes (Exported Files and Exported Files - Mapping Logic Disabled) to use the recommended DPA mode. v Appendix B, Getting help and technical assistance Provides details about contacting IBM Support.

Publications
The IBM WebSphere DataPower library is organized into the following categories: v Installation and upgrade documentation v Administration documentation on page vi v v v v v Development documentation on page vi Reference documentation on page vii Integration documentation on page vii Problem determination documentation on page vii Supplemental documentations on page vii

Installation and upgrade documentation

v IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide

Copyright IBM Corp. 2006, 2009

Provides instructions for installing and powering up the Type 7993 (9003) appliance, creating a startup configuration script, and placing the appliance in operation. v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide Provides instructions for installing and powering up the Type 9235 appliance, creating a startup configuration script, and placing the appliance in operation. v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware Problem Determination and Service Guide Provides information about diagnosing and troubleshooting hardware problems, ordering consumable replacement parts, and replacing parts. v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation 2 Firmware Provides instructions for upgrading Generation 2 firmware and for rolling back firmware upgrades.

Administration documentation
v IBM WebSphere DataPower SOA Appliances: Appliance Overview Provides an introduction and understanding of the IBM Websphere DataPower SOA appliances. v IBM WebSphere DataPower SOA Appliances: Administrators Guide Provides instructions for using the DataPower GUI for managing user access, network access, appliance configuration and system configuration of the appliance. v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide A user guide for using a Hardware Security Module (HSM) installed in the appliance.

Development documentation
v IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide Provides instructions for using the WebGUI to configure XSL Proxy and XSL Co-Processor services. v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide Provides instructions for using the WebGUI to configure XML Firewall services. v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide Provides instructions for using the WebGUI to configure Web Application Firewall services. v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide Provides instructions for using the WebGUI to configure Multiple-Protocol Gateway services. v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide Provides instructions for using the WebGUI to configure Web Service Proxy services. v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide Provides instructions for using the WebGUI to configure B2B Gateway services. v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers Guide

vi

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Provides instructions for using the WebGUI to configure a DataPower appliance for low latency messaging.

Reference documentation
v Product-specific documentation for using commands from the command line. The documentation is specific to each of the following products. Each document provides an alphabetical listing of all commands with syntactical and functional descriptions. IBM WebSphere DataPower XML Accelerator XA35: Command Reference IBM WebSphere DataPower XML Security Gateway XS40: Command Reference IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference IBM WebSphere DataPower B2B Appliance XB60: Command Reference IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command Reference v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog Provides programming information about the usage of DataPower XSLT extension elements and extension functions.

Integration documentation
The following documents are available for managing the integration of related products that can be associated with the DataPower appliance: v IBM WebSphere DataPower SOA Appliances: Integrating with ITCAM Provides concepts for integrating the DataPower appliance with IBM Tivoli Composite Application Management for SOA. v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender Provides concepts for integrating the DataPower appliance with WebSphere Transformer Extender. v IBM WebSphere DataPower XML Integration Appliance XI50: WebSphere MQ Interoperability Explains the concepts and common use patterns for connecting DataPower services to WebSphere MQ systems.

Problem determination documentation

v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide Provides troubleshooting and debugging tools.

Supplemental documentations
v IBM WebSphere DataPower SOA Appliances: Understanding Web Services Policy Provides conceptual information about how the DataPower appliance can use Web Services Policy (WS-Policy). v IBM WebSphere DataPower SOA Appliances: Understanding WS-Addressing Provides conceptual information about how the DataPower appliance can use WS-Addressing. v IBM WebSphere DataPower SOA Appliances: Understanding LTPA Provides conceptual information about how the DataPower appliance can use Lightweight Third Party Authentication. v IBM WebSphere DataPower SOA Appliances: Understanding SPNEGO
Preface

vii

Provides conceptual information about how the DataPower appliance can use SPNEGO. v IBM WebSphere DataPower SOA Appliances: Optimizing through Streaming Provides conceptual information about and procedures for optimizing the DataPower appliance through streaming. v IBM WebSphere DataPower SOA Appliances: Securing the Last Mile Provides conceptual information about and procedures for understanding the DataPower appliance while securing the last mile. v IBM WebSphere DataPower SOA Appliances: Configuring the DoD PKI Provides conceptual information about and procedures for configuring the DataPower appliance with Department of Defense Public Key Infrastructure.

Typeface conventions
The following typeface conventions are used in the documentation: bold italics Identifies commands, programming keywords, and GUI controls. Identifies words and phrases used for emphasis and user-supplied variables.

monospaced Identifies user-supplied input or computer output.

viii

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Chapter 1. Overview
You can use WebSphere Transformation Extender (WTX) Design Studio to perform design-time functions, including create transformation maps to be used by an IBM DataPower appliance to transform message data from binary to XML. After the transformation, the DataPower appliance can perform other processing actions (validate, transform, route) on the XML message. The DataPower appliance can also use maps to transform message data from XML to binary. Design Studio can be used in combination with any IBM WebSphere DataPower appliance that has the DataGlue license to perform the following tasks: v Create data objects to define the structure of your data, including source and target data structures v Develop maps to define the logic for data transformation The process for deploying a transformation map in the DataPower appliance, which you have generated in Design Studio, is as follows: 1. If you have not already done so, configure WTX Design Studio to communicate with the DataPower appliance. 2. Configure the DataPower appliance by importing the WTX domain to the DataPower appliance. For detailed steps, see Importing the test domain on page 8. 3. Using WTX Design Studio: a. Build the WebSphere DataPower map using the DataPower runtime option to convert binary messages to XML. b. Test the WebSphere DataPower map against a DataPower appliance. 4. Upload the compiled WebSphere DataPower map file (*.dpa) to the local: directory on the DataPower appliance. 5. Using the WebGUI: a. Define a Transform Binary processing action to transform incoming messages using the WebSphere DataPower map. b. Test the defined Transform Binary processing action. c. Deploy to production the policy containing the Transform Binary processing action. After you have used Design Studio to develop a transformation map for a particular type of binary message, you can compile and test the map using a DataPower appliance. After the transformation map is fully developed, to test it in a production-like environment with the same DataPower appliance, you must first configure the DataPower appliance. For detailed information about configuring the DataPower appliance, see Configuring the DataPower appliance on page 7. For information about using WTX in a DataPower environment, see the Map Designer documentation in the WTX Information Center at the following Web site: http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp

Software requirements
The supported versions of WTX Design Studio are:
Copyright IBM Corp. 2006, 2009

v To create maps or recompile existing maps to run in the recommended DPA (DataPower Appliance) mode or the deprecated non-DPA modes, use version 8.2.0.3 of WTX Design Studio with the following patch: IBM WebSphere Transformation Extender DataPower Extension Update To obtain this patch, contact WTX Technical Support. v To create or update maps to run in the deprecated non-DPA modes, use WTX Design Studio 8.2.0.3 prior to the following patch: IBM WebSphere Transformation Extender DataPower Extension Update The following table contains detailed information on the WTX releases and their support of DataPower modes:
Table 1. WTX releases and DataPower modes WTX release 8.1 or earlier, 8.1.0.0, 8.1.0.1 8.1.0.2, 8.1.0.3, 8.1.0.4 DataPower Mode support No DataPower Support in Design Studio. Supports Exported files mode in Design Studio. DPA mode is not supported in Design Studio. Can work with 3.7.x releases wherever DataGlue is supported. Supports Exported files mode in Design Studio. DPA mode is not supported in Design Studio. Can work with 3.7.x releases wherever DataGlue is supported. Supports DPA mode in the Design Studio. Exported Files mode is not supported in Design Studio. Can work with 3.7.2 or higher releases only, wherever DataGlue is supported. Design Studio reports an error if the user tries to communicate with an appliance that has a release earlier than 3.7.2.

8.2.0.0, 8.2.0.1, 8.2.0.2, 8.2.0.3

8.2.0.3 with Patch: IBM WebSphere Transformation Extender DataPower Extension Update

Compatibility with existing maps

In 3.7.2 DataPower, the Exported Files and Exported Files - Mapping Logic Disabled modes have been deprecated. For information about these deprecated modes, refer to the DataPower online help. You can continue to use your existing maps with 3.7.2 unchanged or you can follow the migration procedure in Appendix A, Migrating to DPA mode, on page 13 to upgrade your existing maps to use the recommended DPA mode. For information about generating maps in WTX Design Studio using the deprecated modes, see the Map Designer documentation in the WTX Information Center at the following Web site: http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp

Limitations and restrictions

This section contains information about unsupported WTX functions and limitations in DataPower. Depending on the WTX Map Mode you are using, refer to DPA Mode or Exported Files Mode.

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

DPA Mode
DPA is the recommended WTX Map Mode in 3.7.2. To use this mode, you must be running version 8.2.0.3 with the IBM WebSphere Transformation Extender DataPower Extension Update patch or later of WTX Design Studio. If you are using DPA as the WTX Map Mode in the WebGUI (or dpa as the tx-mode command), the following functionality is supported by WTX, but not by DataPower: v WTX Custom functions v The following WTX functions: DBLOOKUP DBQUERY DDEQUERY EXIT FAIL GET GETANDSET GETDIRECTORY GETFILENAME GETRESOURCENAME HANDLEIN

JEXIT OFFSET PUT RUN VALID WTX on DataPower does not support or has limitations and known issues regarding the following functionality: Unsupported: v Because all text is internally represented as XML, the WTX engine does not support null characters in character text. The WTX engine supports NULL in binary text. v DataPower does not support the WTX WSDL importer. v The WTX engine does not support WTX industry packs. v The WTX engine does not support non-constant component rules (anything other than $ = "some-value" where "some-value" is a string literal or a numeric constant), and they are ignored with a warning message during map compilation for DataPower. v The WTX engine does not handle data in error. If the input contains invalid data, the WTX engine aborts the transaction and cannot continue processing. In other words, the WTX engine does not support functions that deal with errors. Examples of this type of function are the CONTAINSERRORS, COUNTABS, ISERROR, ONERROR, or REJECT function. Limitations and known issues: v Because all dates and times are internally represented with the XML schema xs:dateTime function, these values cannot have a value with year zero.

Chapter 1. Overview

v Although the native WTX implementation ignores trailing data that is not valid with a warning message, the WTX engine rejects the entire input as invalid.

Exported Files Mode and Exported Files Mapping Logic Disabled Mode
Exported Files and Exported Files - Mapping Logic Disabled as the WTX Map Mode are deprecated in 3.7.2. With the tx-mode command in the CLI, Exported Files is the default value and Exported Files Mapping Logic Disabled is the no-map value. If you are using either of these modes, the following functionality is supported by WTX, but not by DataPower: v WTX Custom functions v The following WTX functions: DBLOOKUP DBQUERY DDEQUERY EXIT FAIL GET GETANDSET GETDIRECTORY GETFILENAME GETRESOURCENAME HANDLEIN JEXIT OFFSET

PUT RUN VALID WTX on DataPower does not support or has limitations and known issues regarding the following functionality: Unsupported: v Because all text is internally represented as XML, the WTX engine does not support null characters in character text. The WTX engine supports NULL in binary text. v DataPower does not support the WTX WSDL importer. v The WTX engine does not support WTX industry packs. v Component syntax is not supported for unordered groups or for choice groups. Syntax must be attached to the components of the choice group or unordered group. v The WTX engine does not support non-constant component rules (anything other than $ = "some-value" where "some-value" is a string literal), and they are ignored during compilation of the exported files on DataPower with a warning message. Non-constant component rules cannot be used to disambiguate optional inputs (or choice groups).

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

v The WTX engine does not support the Ignore Case property. You must enumerate all value restrictions in a case-sensitive fashion. v In character decimals, the WTX engine does not support variable fraction separators. Fraction syntax must be a literal. v The WTX engine does not support the <WSP> and <OWSP> special literals. v The WTX engine does not support the Floating Component property of choice groups. v The WTX engine does not handle data in error. If the input contains invalid data, the WTX engine aborts the transaction and cannot continue processing. In other words, the WTX engine does not support functions that deal with errors. Examples of this type of function are the CONTAINSERRORS, COUNTABS, ISERROR, ONERROR, or REJECT function. v The WTX engine does not support the following idiom:
boolean-expression = TRUE / boolean-expression = FALSE

You can use boolean-expression by itself or, if appropriate, use NOT. Limitations and known issues: v Because all dates and times are internally represented with the XML schema xs:dateTime function, these values cannot have a value with year zero. v Although the native WTX implementation ignores trailing data that is not valid with a warning message, the WTX engine rejects the entire input as invalid. v In WTX Design Studio, a variable-length component can be sized by its immediately preceding component. The DataPower WTX engine supports the sizing of simple items only. Groups, repeated items, and items with syntax (initiators, terminators, and so forth) are not allowed to be sized. v The WTX engine ignores exclusive value and range restrictions with a warning message. The WTX engine is more lenient on input than the native WTX implementation. This discrepancy in strictness should not affect valid input. v Binary operators (=, !=, +, and so forth) cannot be used where one operand is a series and the other is a singleton. To work around this issue, use a functional map. v The WTX engine might not automatically convert binary text to character text on output. Use the TEXT() function. v The WTX engine does not remove trailing precision on output for zoned numbers or when using the ZONE function. v Overflow might result in ####### when outputting character numbers that have implied places.

Chapter 1. Overview

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Chapter 2. Steps for developing and deploying maps

Configuring Design Studio
When you configure Design Studio to communicate with the DataPower appliance, ensure that you specify the following information: v The IP address or hostname of the DataPower Ethernet interface v The port of the DataPower service For detailed instructions, see the Map Designer documentation in the WTX Information Center at the following Web site: http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp

Configuring the DataPower appliance

The DataPower Resource Kit CD includes valid service configurations to let you quickly view a Design Studio map deployment on a DataPower appliance. Two of the service configurations (tx-test and tx-test-https) are required for map development in Design Studio. For detailed information about importing the test domain that contains these services, see Importing the test domain on page 8. The Resource Kit CD includes the following three service configurations: v tx-test, a service that uses HTTP. The tx-test service uses dynamic named inputs and outputs. It can process a single input and output or multiple inputs and outputs. This service is required for map development in Design Studio. v tx-test-https, a service that uses HTTPS. To use this service, you must first create and configure the required key-certificate pair in Design Studio. The HTTPS sample configuration uses the dtxkey.pem file for the key and the dtxcert.der file for the certificate. This service is required for map development in Design Studio. For more information, see Creating cryptographic material for the HTTPS service. v deployed-tx-test, a service that uses HTTP. The deployed-tx-test service provides configuration examples of the deployment of various scenarios, such as multiple inputs and outputs.

Creating cryptographic material for the HTTPS service

For the HTTPS service, ensure that you perform the following configurations before establishing the HTTPS secure transport: 1. In Design Studio, create the private key (*.pem file) and public certificate (*.der file). 2. On the DataPower appliance, upload this cryptographic material to the cert: directory. Because the tx-test-https service uses HTTPS, ensure that you create the following required cryptographic material in Design Studio: v The dtxkey.pem file v The dtxcert.der file When adding a certificate in Design Studio, specify the following information:

Copyright IBM Corp. 2006, 2009

v In the Certificate area, the fully qualified name of the dtxcert.der file in the File field. v In the Distinguished Name area, the hostname of the DataPower Ethernet interface in the Common Name field. v In the Private key area, the fully qualified name of the dtxkey.pem file in the File field. For complete details about adding a certificate, see the Map Designer documentation in the WTX Information Center at the following Web site: http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp After creating these files, upload them to the cert: directory of the DataPower appliance.

Importing the test domain

To configure the DataPower appliance, use the following procedure: 1. Log in to the DataPower appliance. 2. Import the sample configuration. a. From the Control Panel, click the Import Configuration icon to open the Import Configuration page. b. Click Browse to navigate the local workstation file system. Navigate to the location of the /WTX/export-wtx-dev.zip file on the Resource Kit CD provided with each DataPower appliance. c. d. e. f. Click Next. Select the check box to import the WTX domain. Click Restore. After the import completes, click Done.

3. Validate the import. a. Select WTX from the Domain list in the upper right corner of the WebGUI to switch to the WTX domain. b. From the Control Panel, click the XML Firewall icon to display the firewall catalog. The catalog should contain the following services: v deployed-tx-test v tx-test v tx-test-https If the tx-test-https services is [down], the required cryptographic material was not uploaded to the DataPower appliance or was uploaded but not placed in the cert: directory. For details about creating and uploading these files, see Creating cryptographic material for the HTTPS service on page 7. 4. Log out of the DataPower appliance.

Testing the tx-test XML Firewall service

The successful installation of the service should now be tested. Testing consists of sending requests to the DataPower service and verifying that the correct reply is received. This test uses the curl program, but you can use another utility that can send files to an HTTP address.

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

To test the configuration use the following procedure: 1. Locate the /WTX/wtx.swa sample submission on the Resource Kit CD, which is the same directory as the configuration ZIP file. 2. Send the wtx.swa sample submission to the DataPower service with the following command, but replace x.x.x.x with the IP address of the DataPower Ethernet interface.
curl --data-binary @wtx.swa http://x.x.x.x:22222 -H "Content-Type: multipart/related; type=\"text/xml\"; boundary=\"MIME_Part_7\""

The DataPower service should respond with a reply that begins as follows:
--b7b2e61c-283d-4a1d-8ea4-dab4caa951a4 content-type: text/xml Content-Transfer-Encoding: binary <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:tx-ef="http://www.datapower.com/tx-test" xmlns:tx-dpa="http://www.datapower.com/tx-test/mode/dpa" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <tx-dpa:result> <result-code value="0"/> <output href="cid:Label.txt" name="LabelCard"/> <log href="cid:WDPExecutionLog"/> </tx-dpa:result> </SOAP-ENV:Body> </SOAP-ENV:Envelope> --b7b2e61c-283d-4a1d-8ea4-dab4caa951a4 Content-ID: <Label.txt> Content-Transfer-Encoding: binary Adams, James ABC Co. 29 Frankford Rd Bloomington, IL 60525 --b7b2e61c-283d-4a1d-8ea4-dab4caa951a4 Content-ID: <WDPExecutionLog> Content-Transfer-Encoding: binary

Developing and testing maps in Design Studio

Develop and test maps in Design Studio to ensure that they work correctly with the DataPower appliance. When developing and testing maps in Design Studio, ensure that you set the map run time as WebSphere DataPower. During the development and testing phase, running a transformation map in Design Studio attaches the transformation map and input files to a request message that is sent to the appliance. The appliance processes the request and returns the output of the transformation, along with the log events, in the response message. Events that the appliance encounters during testing are displayed in Design Studio. For information about events that were encountered when running WTX maps, see the Map Designer documentation in the WTX Information Center at the following Web site: http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp
Chapter 2. Steps for developing and deploying maps

You can also examine the DataPower appliance log files. For details about viewing log files, see the service-specific Developers Guide.

Uploading the map files to the DataPower appliance

When the development phase in Design Studio is complete, move the set of compiled transformation map files from Design Studio to the DataPower appliance. To move a DPA map file to the DataPower appliance, use the following procedure: 1. Log into the WebGUI from the work station where the map file resides. 2. Upload the map files to the local: directory of the appropriate application domain on the DataPower appliance.

Defining a WTX transform action in DataPower

To use a transformation map in a DataPower processing policy, you must create a Transform Binary processing action. This processing action performs a binary-to-XML, XML-to-binary, or binary-to-binary transformation. Note: Defining a Transform Binary action requires that the DataPower appliance be licensed for DataGlue. A transformation map can use one or more input contexts, and create results in one or more output contexts. Before you define inputs and outputs, you must first create the DataPower service, processing policy, and processing rule, as described in your service-specific Developers Guide. When creating a Transform Binary action for a WTX map, define the following properties: WTX Map File Fully qualified name of the map file. Locate Named Inputs and Outputs Indicates how the transform determines the input contexts and the output contexts. The following choices are available: Default Use when the map has one or fewer input cards and one or fewer output cards. For detailed steps, see Defining a single input and output on page 11. Explicit Use when the map has multiple input and output cards. In this case, you must explicitly define the contexts that correspond to the cards. For detailed steps, see Defining multiple inputs and outputs on page 11. Dynamic This option exists only for testing WTX Design Studio with DataPower. It is not recommended for normal usage. For details about these properties, see the online help from the WebGUI or command line.

10

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Defining a single input and output

When defining input and output contexts, select the service-specific processing policy from the Services menu. This example is for an XML Firewall service and uses an XML Firewall Policy. When the transformation map has only one input and has only one output, use the following procedure: 1. Select Services XML Firewall XML Firewall Policy to display the catalog. 2. Click the processing policy for the DataPower service. 3. Drag the Advanced icon to the configuration path (the horizontal line). 4. Double-click the Advanced icon to display a window that lists the advanced action types. 5. Click the Transform Binary radio button. 6. Click Next. 7. Specify the input context in the Input field. 8. Specify the URL for the exported map file that was previously uploaded in the WTX Map File field. This URL is similar to local:///recipe.dpa. 9. Retain the default value of DPA from the WTX Map Mode list. 10. Specify the output context in the Output field. 11. Click Done. 12. Click Apply Policy.

Defining multiple inputs and outputs

When the transformation map defines either multiple inputs or multiple outputs, use the following procedure: 1. Create the Transform Binary action as if the transformation map takes only one input and creates only one output. Record the name of the action. For details, see Defining a single input and output. 2. Select Objects XML Processing Processing Action to display the catalog. 3. Click the name of the previously created action. 4. Select Explicit from the Locate Named Inputs and Outputs list. 5. Define explicit named inputs. a. Click the Named Inputs tab. b. Click Add. 1) Specify the name of an input that is expected by the map in the Name field. This must be the same as a cardname in the map file. 2) Specify the name of the DataPower context to contain the input data in the Context field. 3) Click Apply. c. Repeat the previous step to create another named input. 6. Define named outputs. a. Click the Named Outputs tab. b. Click Add. 1) Specify the name of an output that is expected by the map in the Name field. This must be the same as a cardname in the map file. 2) Specify the name of the DataPower processing context that will contain the output data in the Context field. 3) Click Apply. c. Repeat the previous step to create another named output.
Chapter 2. Steps for developing and deploying maps

11

7. Click Apply. When the transform completes, use this context in the next processing action in the processing rule to send the data to the desired destination.

12

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Appendix A. Migrating to DPA mode

Existing maps that use one of the deprecated map modes will continue to work in the current release. The deprecated modes are: v Exported Files v Exported Files - Mapping Logic Disabled For information about these deprecated modes, refer to the online DataPower help. However, DPA is the recommended map mode for all new maps. To use DPA mode, apply the IBM WebSphere Transformation Extender DataPower Extension Update patch to version 8.2.0.3 of Design Studio. No previous version of Design Studio supports DPA mode. To obtain the patch, contact WTX Technical Support.

Converting .mms and .mtt files

If you have the original binary map (.mms) and type tree (.mtt) files, use the following procedure: 1. Open them in Design Studio. 2. Rebuild the map. 3. Upload the map to DataPower. 4. Update the Transform Binary action. a. Change the name of the map file to the new name. b. Change the WTX Map Mode to DPA. c. Click Apply. d. Click Save Config.

Converting .xml and .mts files

If you only have the exported map (.xml) and exported type tree (.mts) files, use the following procedure: 1. Import them to Design Studio. 2. Rebuild the map. 3. Upload the map to DataPower. 4. Update the Transform Binary action. a. Change the name of the map file to the new name. b. Change the WTX Map Mode to DPA. c. Click Apply. d. Click Save Config.

Copyright IBM Corp. 2006, 2009

13

14

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Appendix B. Getting help and technical assistance

This section describes the following options for obtaining support for IBM products: v Searching knowledge bases v Getting a fix v Contacting IBM Support on page 16

Searching knowledge bases

If you encounter a problem, you want it resolved quickly. You can search the available knowledge bases to determine whether the resolution to your problem was already encountered and is already documented. Documentation The IBM WebSphere DataPower documentation library provides extensive documentation in Portable Document Format (PDF). You can use the search function of Adobe Acrobat to query information. If you download and store the documents in a single location, you can use the search facility to find all references across the documentation set. IBM Support If you cannot find an answer in the documentation, use the Search Support feature from the product-specific support page. From the Search Support (this product) area of the product-specific support page, you can search the following IBM resources: v IBM technote database v IBM downloads v IBM Redbooks v IBM developerWorks

Getting a fix
A product fix might be available to resolve your problem. To determine what fixes are available for your IBM product, check the product support site by performing the following steps: 1. Go to the IBM Support site at the following Web address: http://www.ibm.com/support 2. Select Support & Downloads Download to open the Support & downloads page. 3. From the Category list, select WebSphere. 4. From the Sub-Category list, select WebSphere DataPower SOA Appliances. 5. Click the GO icon to display the list of most recent updates. 6. Click the link for the firmware and documentation download that is specific to your WebSphere DataPower product. 7. Follow the instructions in the technote to download the fix.

Copyright IBM Corp. 2006, 2009

15

Contacting IBM Support

IBM Support provides assistance with product defects. Before contacting IBM Support, the following criteria must be met: v Your company has an active maintenance contract. v You are authorized to submit problems. To contact IBM Support with a problem, use the following procedure: 1. Define the problem, gather background information, and determine the severity of the problem. For help, refer to the Software Support Handbook. To access the online version of this handbook, use the following procedure: a. Access the IBM Software Support Web page at the following Web address: http://www.ibm.com/software/support b. Scroll down to the Additional support links section of the page. c. Under Support tools, click the Software Support Handbook link. d. Bookmark this page for future reference. From this page, you can obtain a PDF copy of the handbook. 2. Gather diagnostic information. a. Access the product support at the following Web address: http://www.ibm.com/software/integration/datapower/support b. Locate the Assistance area of the product support page. c. Click Information to include to access that technote that lists the information that is required to report a problem. 3. Submit the problem in one of the following ways: Online From the IBM Support Web site (http://www.ibm.com/support), select Support & Downloads Open a service request. Following the instructions. By phone For the phone number to call in your country, refer to Contacts in the Software Support Handbook. From the Software Support Handbook Web site, click Contacts. In the U.S. and Canada, call 1800IBM-SERV (18004267378) and select option 2 for software. If the problem you should submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an authorized program analysis report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered.

16

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Appendix C. Notices and trademarks

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements or changes in the product(s) or the program(s) described in this publication at any time without notice.

Trademarks
IBM, the IBM logo, developerWorks, DB2, DataPower, IMS, RACF, Redbooks, Tivoli, WebSphere, and z/OS are registered trademarks of the International Business Machines Corporation in the United States or other countries. Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Copyright IBM Corp. 2006, 2009

17

Other company, product, and service names may be trademarks or service marks of others.

18

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Index B
bold typeface viii

L
licensing sending inquiries 17 Locate Named Inputs and Outputs default 10 dynamic 10 explicit 10

C
cryptographic material creating for the HTTPS service 7 customer support contacting 16 obtaining fixes 15 searching knowledge bases 15

M
map deployment process high-level steps 1 monospaced typeface viii

D
DataPower configuring for WTX 7 defining a WTX transform action 10 uploading map files 10 deprecated modes compatibility of existing maps 2 migrating to DPA mode 13 Design Studio configuring for DataPower 7 developing and testing maps 9 overview 1 documentation conventions, typefaces viii DPA mode converting files 13 migrating to 13

N
notices 17

P
patents 17

R
Resource Kit 7, 8

S
software requirements 1 support See customer support

E
existing maps compatibility of deprecated modes 2

T
test domain importing 8 trademarks 17 tx-test XML Firewall service testing 8 typeface conventions viii

F
fixes, obtaining 15

H
HTTPS service creating cryptographic material 7

W
WTX limitations and restrictions DPA mode 2 Exported Files mode 4 WTX Map File 10 WTX versions support for DataPower modes

I
input and output contexts multiple inputs and outputs single input and output 11 intellectual property 17 italics typeface viii 11

K
knowledge bases searching 15 Copyright IBM Corp. 2006, 2009

19

20

IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender

Printed in USA