Datapower IntegratingWithWTX-v1

WebSphere® DataPower SOA Appliances

Integrating with WebSphere Transformation Extender

��

NoteBefore 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 otherwiseindicated 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 Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . vWho should read this document . . . . . . . . vHow this document is organized . . . . . . . vPublications . . . . . . . . . . . . . . v

Installation and upgrade documentation . . . . vAdministration documentation . . . . . . . viDevelopment documentation. . . . . . . . viReference documentation. . . . . . . . . viiIntegration documentation . . . . . . . . viiProblem determination documentation . . . . viiSupplemental documentations . . . . . . . vii

Typeface conventions . . . . . . . . . . . viii

Chapter 1. Overview . . . . . . . . . 1Software requirements . . . . . . . . . . . 1Compatibility with existing maps . . . . . . . 2Limitations and restrictions . . . . . . . . . 2

DPA Mode . . . . . . . . . . . . . . 3Exported Files Mode and Exported Files –Mapping Logic Disabled Mode . . . . . . . 4

Chapter 2. Steps for developing anddeploying maps . . . . . . . . . . . 7Configuring Design Studio . . . . . . . . . 7Configuring the DataPower appliance . . . . . . 7

Creating cryptographic material for the HTTPSservice . . . . . . . . . . . . . . . 7Importing the test domain . . . . . . . . . 8Testing the tx-test XML Firewall service . . . . 8

Developing and testing maps in Design Studio . . . 9Uploading the map files to the DataPower appliance 10Defining a WTX transform action in DataPower . . 10

Defining a single input and output . . . . . 11Defining multiple inputs and outputs. . . . . 11

Appendix A. Migrating to DPA mode . . 13Converting .mms and .mtt files . . . . . . . . 13Converting .xml and .mts files . . . . . . . . 13

Appendix B. Getting help and technicalassistance . . . . . . . . . . . . . 15Searching knowledge bases . . . . . . . . . 15Getting a fix . . . . . . . . . . . . . . 15Contacting IBM Support . . . . . . . . . . 16

Appendix C. Notices and trademarks 17Trademarks . . . . . . . . . . . . . . 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-deployNetwork appliances that simplify, help secure, and accelerate your XML and WebServices deployments while extending your SOA infrastructure. These appliancesoffer an innovative, pragmatic approach to harness the power of SOA whilesimultaneously enabling you to leverage the value of your existing application,security, and Networking infrastructure investments.

Who should read this documentThis document is intended for developers who will use WebSphere TransformationExtender (WTX) Design Studio to create transformation maps to be used by anIBM DataPower appliance to transform message data from binary to XML.

How this document is organizedThis 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 transformationmaps to be used by an IBM DataPower appliance to transform message datafrom binary to XML.

v Chapter 2, “Steps for developing and deploying maps”Provides procedures for developing maps in Design Studio, deploying maps tothe DataPower appliance, and creating transform actions for DataPower servicesthat use maps.

v Appendix A, “Migrating to DPA mode”Provides migration procedures to upgrade existing maps that use deprecatedmap modes (Exported Files and Exported Files - Mapping Logic Disabled) touse the recommended DPA mode.

v Appendix B, “Getting help and technical assistance”Provides details about contacting IBM Support.

PublicationsThe IBM WebSphere DataPower library is organized into the following categories:v “Installation and upgrade documentation”v “Administration documentation” on page viv “Development documentation” on page viv “Reference documentation” on page viiv “Integration documentation” on page viiv “Problem determination documentation” on page viiv “Supplemental documentations” on page vii

Installation and upgrade documentationv IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide

© Copyright IBM Corp. 2006, 2009 v

Provides instructions for installing and powering up the Type 7993 (9003)appliance, creating a startup configuration script, and placing the appliance inoperation.

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 ProblemDetermination 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: Generation2 Firmware

Provides instructions for upgrading Generation 2 firmware and for rolling backfirmware upgrades.

Administration documentationv IBM WebSphere DataPower SOA Appliances: Appliance Overview

Provides an introduction and understanding of the IBM Websphere DataPowerSOA 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 theappliance.

v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide

A user guide for using a Hardware Security Module (HSM) installed in theappliance.

Development documentationv IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide

Provides instructions for using the WebGUI to configure XSL Proxy and XSLCo-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 ApplicationFirewall services.

v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway DevelopersGuide

Provides instructions for using the WebGUI to configure Multiple-ProtocolGateway services.

v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide

Provides instructions for using the WebGUI to configure Web Service Proxyservices.

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 appliancefor low latency messaging.

Reference documentationv Product-specific documentation for using commands from the command line.

The documentation is specific to each of the following products. Each documentprovides an alphabetical listing of all commands with syntactical and functionaldescriptions.– 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: CommandReference

v IBM WebSphere DataPower SOA Appliances: Extension Elements and FunctionsCatalog

Provides programming information about the usage of DataPower XSLTextension elements and extension functions.

Integration documentationThe following documents are available for managing the integration of relatedproducts 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 TivoliComposite Application Management for SOA.

v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphereTransformation Extender

Provides concepts for integrating the DataPower appliance with WebSphereTransformer Extender.

v IBM WebSphere DataPower XML Integration Appliance XI50: WebSphere MQInteroperability

Explains the concepts and common use patterns for connecting DataPowerservices to WebSphere MQ systems.

Problem determination documentationv IBM WebSphere DataPower SOA Appliances: Problem Determination Guide

Provides troubleshooting and debugging tools.

Supplemental documentationsv IBM WebSphere DataPower SOA Appliances: Understanding Web Services Policy

Provides conceptual information about how the DataPower appliance can useWeb Services Policy (WS-Policy).

v IBM WebSphere DataPower SOA Appliances: Understanding WS-Addressing

Provides conceptual information about how the DataPower appliance can useWS-Addressing.

v IBM WebSphere DataPower SOA Appliances: Understanding LTPA

Provides conceptual information about how the DataPower appliance can useLightweight Third Party Authentication.

v IBM WebSphere DataPower SOA Appliances: Understanding SPNEGO

Preface vii

Provides conceptual information about how the DataPower appliance can useSPNEGO.

v IBM WebSphere DataPower SOA Appliances: Optimizing through Streaming

Provides conceptual information about and procedures for optimizing theDataPower appliance through streaming.

v IBM WebSphere DataPower SOA Appliances: Securing the Last Mile

Provides conceptual information about and procedures for understanding theDataPower appliance while securing the last mile.

v IBM WebSphere DataPower SOA Appliances: Configuring the DoD PKI

Provides conceptual information about and procedures for configuring theDataPower appliance with Department of Defense Public Key Infrastructure.

Typeface conventionsThe following typeface conventions are used in the documentation:

bold Identifies commands, programming keywords, and GUI controls.

italics Identifies words and phrases used for emphasis and user-suppliedvariables.

monospacedIdentifies 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 performdesign-time functions, including create transformation maps to be used by an IBMDataPower appliance to transform message data from binary to XML. After thetransformation, the DataPower appliance can perform other processing actions(validate, transform, route) on the XML message. The DataPower appliance canalso use maps to transform message data from XML to binary.

Design Studio can be used in combination with any IBM WebSphere DataPowerappliance 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 structuresv 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” onpage 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 aparticular type of binary message, you can compile and test the map using aDataPower appliance. After the transformation map is fully developed, to test it ina production-like environment with the same DataPower appliance, you must firstconfigure the DataPower appliance. For detailed information about configuring theDataPower appliance, see “Configuring the DataPower appliance” on page 7.

For information about using WTX in a DataPower environment, see the MapDesigner documentation in the WTX Information Center at the following Web site:

http://publib.boulder.ibm.com/infocenter/wtxdoc/v8r2m0/index.jsp

Software requirementsThe supported versions of WTX Design Studio are:

© Copyright IBM Corp. 2006, 2009 1


v To create maps or recompile existing maps to run in the recommended DPA(DataPower Appliance) mode or the deprecated non-DPA modes, use version8.2.0.3 of WTX Design Studio with the following patch:IBM WebSphere Transformation Extender DataPower Extension UpdateTo obtain this patch, contact WTX Technical Support.

v To create or update maps to run in the deprecated non-DPA modes, use WTXDesign 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 theirsupport of DataPower modes:

Table 1. WTX releases and DataPower modes

WTX release DataPower Mode support

8.1 or earlier, 8.1.0.0, 8.1.0.1 No DataPower Support in Design Studio.

8.1.0.2, 8.1.0.3, 8.1.0.4 Supports Exported files mode in DesignStudio. DPA mode is not supported inDesign Studio. Can work with 3.7.x releaseswherever DataGlue is supported.

8.2.0.0, 8.2.0.1, 8.2.0.2, 8.2.0.3 Supports Exported files mode in DesignStudio. DPA mode is not supported inDesign Studio. Can work with 3.7.x releaseswherever DataGlue is supported.

8.2.0.3 with Patch: IBM WebSphereTransformation Extender DataPowerExtension Update

Supports DPA mode in the Design Studio.Exported Files mode is not supported inDesign Studio. Can work with 3.7.2 orhigher releases only, wherever DataGlue issupported. Design Studio reports an error ifthe user tries to communicate with anappliance that has a release earlier than3.7.2.

Compatibility with existing mapsIn 3.7.2 DataPower, the Exported Files and Exported Files - Mapping LogicDisabled modes have been deprecated. For information about these deprecatedmodes, refer to the DataPower online help. You can continue to use your existingmaps with 3.7.2 unchanged or you can follow the migration procedure inAppendix A, “Migrating to DPA mode,” on page 13 to upgrade your existing mapsto use the recommended DPA mode. For information about generating maps inWTX Design Studio using the deprecated modes, see the Map Designerdocumentation in the WTX Information Center at the following Web site:


Limitations and restrictionsThis section contains information about unsupported WTX functions andlimitations in DataPower. Depending on the WTX Map Mode you are using, referto DPA Mode or Exported Files Mode.

2 IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender


DPA ModeDPA is the recommended WTX Map Mode in 3.7.2. To use this mode, you must berunning version 8.2.0.3 with the IBM WebSphere Transformation ExtenderDataPower Extension Update patch or later of WTX Design Studio. If you areusing DPA as the WTX Map Mode in the WebGUI (or dpa as the tx-modecommand), the following functionality is supported by WTX, but not byDataPower:v WTX Custom functionsv 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 issuesregarding 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 inbinary 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 numericconstant), and they are ignored with a warning message during mapcompilation for DataPower.

v The WTX engine does not handle data in error. If the input contains invaliddata, the WTX engine aborts the transaction and cannot continue processing. Inother 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 3

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

Exported Files Mode and Exported Files – Mapping LogicDisabled Mode

Exported Files and Exported Files - Mapping Logic Disabled as the WTX MapMode are deprecated in 3.7.2. With the tx-mode command in the CLI, ExportedFiles is the default value and Exported Files – Mapping Logic Disabled is theno-map value.

If you are using either of these modes, the following functionality is supported byWTX, but not by DataPower:v WTX Custom functionsv 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 issuesregarding 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 inbinary 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 unorderedgroup.

v The WTX engine does not support non-constant component rules (anythingother than $ = "some-value" where "some-value" is a string literal), and they areignored during compilation of the exported files on DataPower with a warningmessage. Non-constant component rules cannot be used to disambiguateoptional inputs (or choice groups).


v The WTX engine does not support the Ignore Case property. You mustenumerate all value restrictions in a case-sensitive fashion.

v In character decimals, the WTX engine does not support variable fractionseparators. 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. Inother 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 thesizing 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 warningmessage. The WTX engine is more lenient on input than the native WTXimplementation. This discrepancy in strictness should not affect valid input.

v Binary operators (=, !=, +, and so forth) cannot be used where one operand is aseries and the other is a singleton. To work around this issue, use a functionalmap.

v The WTX engine might not automatically convert binary text to character text onoutput. Use the TEXT() function.

v The WTX engine does not remove trailing precision on output for zonednumbers or when using the ZONE function.

v Overflow might result in ####### when outputting character numbers that haveimplied places.

Chapter 1. Overview 5

Chapter 2. Steps for developing and deploying maps

Configuring Design StudioWhen 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 interfacev The port of the DataPower service

For detailed instructions, see the Map Designer documentation in the WTXInformation Center at the following Web site:


Configuring the DataPower applianceThe DataPower Resource Kit CD includes valid service configurations to let youquickly view a Design Studio map deployment on a DataPower appliance. Two ofthe service configurations (tx-test and tx-test-https) are required for mapdevelopment in Design Studio. For detailed information about importing the testdomain 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 inputsand 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 firstcreate and configure the required key-certificate pair in Design Studio. TheHTTPS sample configuration uses the dtxkey.pem file for the key and thedtxcert.der file for the certificate. This service is required for map developmentin Design Studio. For more information, see “Creating cryptographic material forthe HTTPS service.”

v deployed-tx-test, a service that uses HTTP. The deployed-tx-test serviceprovides configuration examples of the deployment of various scenarios, such asmultiple inputs and outputs.

Creating cryptographic material for the HTTPS serviceFor the HTTPS service, ensure that you perform the following configurationsbefore 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 thefollowing required cryptographic material in Design Studio:v The dtxkey.pem filev The dtxcert.der file

When adding a certificate in Design Studio, specify the following information:



v In the Certificate area, the fully qualified name of the dtxcert.der file in theFile field.

v In the Distinguished Name area, the hostname of the DataPower Ethernetinterface in the Common Name field.

v In the Private key area, the fully qualified name of the dtxkey.pem file in theFile field.

For complete details about adding a certificate, see the Map Designerdocumentation in the WTX Information Center at the following Web site:


After creating these files, upload them to the cert: directory of the DataPowerappliance.

Importing the test domainTo 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 theImport Configuration page.

b. Click Browse to navigate the local workstation file system. Navigate to thelocation of the /WTX/export-wtx-dev.zip file on the Resource Kit CDprovided with each DataPower appliance.

c. Click Next.d. Select the check box to import the WTX domain.e. Click Restore.f. 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 materialwas not uploaded to the DataPower appliance or was uploaded but notplaced in the cert: directory. For details about creating and uploading thesefiles, see “Creating cryptographic material for the HTTPS service” on page7.

4. Log out of the DataPower appliance.

Testing the tx-test XML Firewall serviceThe successful installation of the service should now be tested. Testing consists ofsending requests to the DataPower service and verifying that the correct reply isreceived. This test uses the curl program, but you can use another utility that cansend files to an HTTP address.



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 DataPowerEthernet 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-dab4caa951a4content-type: text/xmlContent-Transfer-Encoding: binary

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelopexmlns: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-dab4caa951a4Content-ID: <Label.txt>Content-Transfer-Encoding: binary

Adams, JamesABC Co.29 Frankford RdBloomington, IL 60525

--b7b2e61c-283d-4a1d-8ea4-dab4caa951a4Content-ID: <WDPExecutionLog>Content-Transfer-Encoding: binary

Developing and testing maps in Design StudioDevelop and test maps in Design Studio to ensure that they work correctly withthe 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 inDesign Studio attaches the transformation map and input files to a requestmessage that is sent to the appliance. The appliance processes the request andreturns the output of the transformation, along with the log events, in the responsemessage.

Events that the appliance encounters during testing are displayed in Design Studio.For information about events that were encountered when running WTX maps, seethe Map Designer documentation in the WTX Information Center at the followingWeb site:


Chapter 2. Steps for developing and deploying maps 9


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

Uploading the map files to the DataPower applianceWhen the development phase in Design Studio is complete, move the set ofcompiled transformation map files from Design Studio to the DataPowerappliance.

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 DataPowerTo use a transformation map in a DataPower processing policy, you must create aTransform Binary processing action. This processing action performs abinary-to-XML, XML-to-binary, or binary-to-binary transformation.

Note: Defining a Transform Binary action requires that the DataPower appliancebe licensed for DataGlue.

A transformation map can use one or more input contexts, and create results inone 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-specificDevelopers Guide.

When creating a Transform Binary action for a WTX map, define the followingproperties:

WTX Map FileFully qualified name of the map file.

Locate Named Inputs and OutputsIndicates how the transform determines the input contexts and the outputcontexts. The following choices are available:

DefaultUse when the map has one or fewer input cards and one or feweroutput cards. For detailed steps, see “Defining a single input andoutput” on page 11.

ExplicitUse when the map has multiple input and output cards. In thiscase, you must explicitly define the contexts that correspond to thecards. For detailed steps, see “Defining multiple inputs andoutputs” on page 11.

DynamicThis option exists only for testing WTX Design Studio withDataPower. It is not recommended for normal usage.

For details about these properties, see the online help from the WebGUI orcommand line.


Defining a single input and outputWhen defining input and output contexts, select the service-specific processingpolicy from the Services menu. This example is for an XML Firewall service anduses an XML Firewall Policy. When the transformation map has only one inputand 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 outputsWhen 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 Namefield. 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 inthe 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 Namefield. This must be the same as a cardname in the map file.

2) Specify the name of the DataPower processing context that will containthe 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 theprocessing rule to send the data to the desired destination.


Appendix A. Migrating to DPA mode

Existing maps that use one of the deprecated map modes will continue to work inthe 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 DPAmode, apply the IBM WebSphere Transformation Extender DataPower ExtensionUpdate patch to version 8.2.0.3 of Design Studio. No previous version of DesignStudio supports DPA mode. To obtain the patch, contact WTX Technical Support.

Converting .mms and .mtt filesIf you have the original binary map (.mms) and type tree (.mtt) files, use thefollowing 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 filesIf you only have the exported map (.xml) and exported type tree (.mts) files, usethe 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.


Appendix B. Getting help and technical assistance

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

Searching knowledge basesIf you encounter a problem, you want it resolved quickly. You can search theavailable knowledge bases to determine whether the resolution to your problemwas already encountered and is already documented.

DocumentationThe IBM WebSphere DataPower documentation library provides extensivedocumentation in Portable Document Format (PDF). You can use thesearch function of Adobe® Acrobat to query information. If you downloadand store the documents in a single location, you can use the search facilityto find all references across the documentation set.

IBM SupportIf you cannot find an answer in the documentation, use the Search Supportfeature from the product-specific support page.

From the Search Support (this product) area of the product-specificsupport page, you can search the following IBM resources:v IBM technote databasev IBM downloadsv IBM Redbooks®

v IBM developerWorks®

Getting a fixA product fix might be available to resolve your problem. To determine what fixesare available for your IBM product, check the product support site by performingthe following steps:1. Go to the IBM Support site at the following Web address:

http://www.ibm.com/support2. 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.


http://www.ibm.com/support

Contacting IBM SupportIBM Support provides assistance with product defects. Before contacting IBMSupport, 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 theonline 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/supportb. 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/supportb. 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:

OnlineFrom the IBM Support Web site (http://www.ibm.com/support), selectSupport & Downloads → Open a service request. Following theinstructions.

By phoneFor the phone number to call in your country, refer to “Contacts” in theSoftware Support Handbook. From the Software Support Handbook Website, click Contacts. In the U.S. and Canada, call 1–800–IBM-SERV(1–800–426–7378) and select option 2 for software.

If the problem you should submit is for a software defect or for missing orinaccurate documentation, IBM Support creates an authorized program analysisreport (APAR). The APAR describes the problem in detail. Whenever possible, IBMSupport provides a workaround that you can implement until the APAR isresolved and a fix is delivered.


http://www.ibm.com/software/support

http://www.ibm.com/software/integration/datapower/support

http://www.ibm.com/support

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 inother countries. Consult your local IBM representative for information about theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS”WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain 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 beincorporated in new editions of the publication. IBM may make improvements orchanges in the product(s) or the program(s) described in this publication at anytime without notice.

TrademarksIBM, the IBM logo, developerWorks, DB2, DataPower, IMS, RACF, Redbooks,Tivoli, WebSphere, and z/OS are registered trademarks of the InternationalBusiness Machines Corporation in the United States or other countries.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,and/or other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.


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


Index

Bbold typeface viii

Ccryptographic material

creating for the HTTPS service 7customer support

contacting 16obtaining fixes 15searching knowledge bases 15

DDataPower

configuring for WTX 7defining a WTX transform action 10uploading map files 10

deprecated modescompatibility of existing maps 2migrating to DPA mode 13

Design Studioconfiguring for DataPower 7developing and testing maps 9overview 1

documentation conventions,typefaces viii

DPA modeconverting files 13migrating to 13

Eexisting maps

compatibility of deprecated modes 2

Ffixes, obtaining 15

HHTTPS service

creating cryptographic material 7

Iinput and output contexts

multiple inputs and outputs 11single input and output 11

intellectual property 17italics typeface viii

Kknowledge bases

searching 15

Llicensing

sending inquiries 17Locate Named Inputs and Outputs

default 10dynamic 10explicit 10

Mmap deployment process

high-level steps 1monospaced typeface viii

Nnotices 17

Ppatents 17

RResource Kit 7, 8

Ssoftware requirements 1support

See customer support

Ttest domain

importing 8trademarks 17tx-test XML Firewall service

testing 8typeface conventions viii

WWTX limitations and restrictions

DPA mode 2Exported Files mode 4

WTX Map File 10WTX versions

support for DataPower modes 1


��

Printed in USA

Datapower IntegratingWithWTX-v1

Documents

Transcript of Datapower IntegratingWithWTX-v1