Level: Intermediate Dave Mulley (dmulley@us.ibm.com), IT Specialist, IBM
20 Feb 2008 This article discusses the configuration required to integrate WebSphere Partner Gateway and WebSphere Transformation Extender. You'll learn about the different invocation methods that WebSphere Transformation Extender supports and when you should use each one with WebSphere Partner Gateway. You'll understand how to use WebSphere Transformation Extender, Java JNI, and Java RMI APIs to integrate WebSphere Partner Gateway and WebSphere Transformation Extender.
Introduction
IBM® WebSphere® Transformation Extender (hereafter called Transformation Extender) is a data transformation and validation engine. Architects, system administrators, and developers that are already familiar with WebSphere Partner Gateway (hereafter called Partner Gateway) will appreciate the numerous patterns WebSphere Transformation Extender provides to extend Partner Gateway's capabilities. This article discusses the integration of Partner Gateway and Transformation Extender for data transformation.
This article provides you with an overview of Transformation Extender and explains how Partner Gateway processes a document from receipt to delivery to the destination. Each of the available integration patterns is outlined and the Java JNI and RMI patterns are covered in depth. After you've read this article, you will have the required information to integrate Partner Gateway and Transformation Extender using either the Java JNI or the Java RMI patterns.
Prerequisite knowledge of WebSphere Partner Gateway and WebSphere Transformation Extender is recommended.
Required product versions and fixes
The case studies covered in this article require the following product versions and fixes:
- WebSphere Partner Gateway Enterprise Edition Version V6.1 and Fix Pack 1
- WebSphere Transformation Extender Design Studio V8.2 and all latest iFixes and Fix Packs
- WebSphere Transformation Extender SDK V8.2 and all latest iFixes and Fix Packs
WebSphere Transformation Extender
WebSphere Transformation Extender V8.2 uses a codeless, graphical approach to development. In this article, you'll focus on the high-volume, transaction-oriented, "any to any" data transformation and validation engine that is the foundation of Transformation Extender. See the Resources section to learn more about the different Transformation Extender offerings from IBM that add functionality to the transformation and validation engine.
Let's begin with a few basics:
- Transformation Extender transformation and validation maps are designed using the Transformation Extender Design Studio and compiled into a platform-specific file that is used by the transformation and validation engine at run time.
- Data formats are described in Transformation Extender using Type Trees. Transformation Extender Industry Packs provide pre-built Type Trees for many standard formats (EDI , HIPAA, and so forth) and wizards are available to generate Type Trees from XML Schemas, COBOL Copy Books and numerous other formats.
-
Cards provide a mechanism to attach metadata to Type Trees. This metadata is made up of parameters including input filename and location (on an Input Card) or output filename and location (on an Output Card). A card also specifies parameters that are used by the transformation and validation engine at runtime including validation levels and what should happen in the event that a warning or error is encountered during processing.
- A Transformation Extender Map typically has one Input Card and one Output Card and a set of transformation and validation rules.
The diagram shown below in Figure 1 shows a Transformation Extender map that transforms data from Format A to Format B.
Figure 1. Transformation Extender Map transforming data from Format A to Format B
The diagram shown below in Figure 2 shows that Transformation Extender supports maps that have multiple Input and Output Cards.
Figure 2. Transformation Extender Map with multiple Input and Output Cards
Invoking Transformation Extender Maps using JNI
Transformation Extender provides a Java API that lets you invoke Transformation Extender maps from Java. Given that Transformation Extender is a C++ application, this Java API uses JNI (Java Native Interface) and requires you to install the Transformation Extender transformation and validation engine on the same physical machine as Partner Gateway.
The code snippet in Listing 1 below shows you how to invoke a Transformation Extender map using the Java API:
Listing 1. Transformation Extender Java API snippet using JNI
import com.ibm.websphere.dtx.dtxpi.MConstants;
import com.ibm.websphere.dtx.dtxpi.MException;
import com.ibm.websphere.dtx.dtxpi.MMap;
...
// Initialize the API
MMap.initializeAPI(null);
// Create a map
MMap map = new MMap("test1.mmc");
// Run the map
map.run();
// Check the return status
int iRC = map.getIntegerProperty(MConstants.MPIP_OBJECT_ERROR_CODE, 0);
String szMsg = map.getTextProperty(MConstants.MPIP_OBJECT_ERROR_MSG, 0);
System.out.println("Map status: " + szMsg + " (" + iRC + ")");
// Clean up
map.unload();
MMap.terminateAPI();
|
Invoking Transformation Extender Maps using RMI
Transformation Extender also provides a Java RMI API that lets you invoke Transformation Extender maps using an RMI (Remote Method Invocation) interface instead of the JNI interface. You can use the RMI interface in instances where the Transformation Extender transformation and validation engine and Partner Gateway are installed on different machines.
The code snippet in Listing 2 below shows you how to invoke a Transformation Extender map using the Java RMI API:
Listing 2. Transformation Extender Java API snippet using RMI
import java.rmi.*;
import com.ibm.websphere.dtx.dtxpi.MConstants;
import com.ibm.websphere.dtx.dtxpi.rmi.*;
…
IMMap map = null;
// Initialize the RMI Connection
IMFactory factory = MRMIAPI.getFactory(hostname, port);
// Load the Map
map = factory.loadMapFile("Z:\\ test1.mmc");
// Run the Map
map.run();
// Check the return status
String responseMessage = map.getTextProperty(MConstants.MPIP_OBJECT_ERROR_MSG, 0);
int resultCode = map.getIntegerProperty(MConstants.MPIP_OBJECT_ERROR_CODE, 0);
System.out.println("Map status: " + szMsg + " (" + iRC + ")");
// Clean up
map.unload();
|
Using Transformation Extender with Partner Gateway
Although this article outlines two supported patterns for integrating WebSphere Transformation Extender with Partner Gateway V6.1 to transform data, only the second method is covered in this article.
Using WebSphere Message Broker
In this pattern, the integration between Partner Gateway and Transformation Extender is in-direct. Partner Gateway passes documents that require transformation to WebSphere Message Broker (hereafter called Message Broker), which in turn invokes the required Transformation Extender map to perform the transformation, and then delivers the transformed document to the target backend application.
Figure 3. Using WebSphere Message Broker
This integration method is not covered in this article.
Using a Partner Gateway "Action" Exit
In this pattern, Partner Gateway invokes Transformation Extender maps directly using either the Java JNI or Java RMI APIs.
To gain an understanding of how Partner Gateway invokes Transformation Extender, study the steps that outline how the WebSphere Partner Gateway Document Manager processes a document, so that it can be delivered to a trading partner in the format and protocol that the trading partner is expecting.
The Business Processing Engine executes a series of workflows (which contain a number of steps) in sequence:
-
fixed inbound workflow performs protocol un-packaging, protocol processing and on the document and then performs connection lookup.
-
variable workflow performs actions on the document that can include validation, transformation and/or translation.
-
fixed outbound workflow performs protocol packaging and then passes the document for delivery to the trading partner.
Figure 4. WebSphere Partner Gateway Document Processing
You can extend each of the workflows with the use of Partner Gateway User Exits, which are custom pieces of Java that can be plugged into Partner Gateway to provide additional functionality.
The invocation of a Transformation Extender Map fits into the category of document validation, transformation and/or translation and therefore a Variable Workflow User Exit is required that is also known as an Action Exit. An Action Exit has full access to the incoming document and can (if required) create a new transformed document and pass it on to the Outbound Workflow for packaging and delivery to the partner. The development of Partner Gateway User Exits is covered in detail in the WebSphere Partner Gateway Information Center (see the Resources section at the end of this article).
The WebSphere Partner Gateway development team has developed a sample Action User Exit that invokes Transformation Extender using either the Transformation Extender Java JNI interface or the Transformation Extender Java RMI interface. You can find this sample on the Partner Gateway installation CD.
Figure 5 (below) shows how the WTX Action Exit fits into the series of workflows.
Figure 5. WebSphere Partner Gateway Document Processing using WTX Action Exit
This pattern allows Partner Gateway to handle the processing of the document from beginning to end, which keeps the amount of configuration required to a minimum and in a single place. It is this pattern that will be discussed in detail in this article.
How to determine which Transformation Extender Java API to use
First, you must decide which Transformation Extender API the Action Exit should use. This is a fairly simple decision to make, since it is dependant upon the configuration of the Transformation Extender/Partner Gateway environment. If Transformation Extender and Partner Gateway are on different physical machines, then the only API available for use is the Transformation Extender Java RMI API. If Transformation Extender and Partner Gateway are on the same physical machine, then either of the APIs can be used, but the Java™ JNI API is recommended as it is faster than the Java RMI API.
Overriding Transformation Extender Cards
When a map is compiled into an executable, the values that are in the Input and Output cards are set as defaults that are used by the Transformation Extender transformation and validation engine when the map is invoked. The values that must be set dynamically to allow the map to be used by Partner Gateway for transformations and validations are:
-
Input Card: Input File Name: the fully qualified name of the file used as input to the map.
-
Output Card: Output File Name: the fully qualified name of the file used as output of the map.
The Transformation Extender Java API allows the default values in the Input and Output cards to be overridden at runtime.
During Partner Gateway BPE Variable Workflow processing, the documents that are being processed are stored in physical files in the Partner Gateway Shared File System directories. Any new documents that are created during processing using the Partner Gateway APIs are also created in physical files in the Partner Gateway Shared File System directories. Each invocation of the Transformation Extender Action Handler will be processing different documents and as a result it is therefore necessary to override the Transformation Extender Map Input and Output cards at runtime to point at the correct files in the WPG Shared File System directories.
Figure 6 Transformation Extender Map using files from the WPG Shared File System
You can use the code snippet in Listing 3 with both the Transformation Extender Java JNI API and the Transformation Extender Java RMI API to set the fully qualified input and output file names at runtime to point to the files in the WPG Shared File System.
Listing 3. Overriding Transformation Extender Input and Output Cards
// Get the first Input Card
MCard inputCard = map.getInputCardObject(1);
// Get the Adapter for the Input Card
MAdapter inputAdapter = inputCard.getAdapter();
// Modify the Input Adapter Command Line
String xml = "<Adapter>" +
"<CommandLine id=\"" + MConstants.MPIP_ADAPTER_COMMANDLINE + "\" type=\"text\">" +
inputFilename +
"</CommandLine>" +
"</Adapter>";
// Set the Adapter Command Line
inputAdapter.setPropertiesXML( xml );
// Get the first Output Card
MCard outputCard = map.getOutputCardObject(1);
MAdapter outputAdapter = outputCard.getAdapter();
// Modify the Output Adapter Command Line
xml = "<Adapter>" +
"<CommandLine id=\"" + MConstants.MPIP_ADAPTER_COMMANDLINE +
"\" type=\"text\">" +
outputFilename +
"</CommandLine>" +
"</Adapter>";
// Set the Adapter Command Line
outputAdapter.setPropertiesXML( xml );
// Run the Map
map.run();
|
Understanding the sample WTX Action Exit
The sample WTX Action Exit that is shipped on the Partner Gateway installation media has an extensible design that is a perfect starting place for all Partner Gateway/Transformation Extender integrations that want to use either the Transformation Extender Java JNI or the Transformation Extender Java RMI APIs. This article discusses only the Transformation Extender-specific portions of the sample. You can find a full, detailed description of the sample in the Partner Gateway Information Center.
The sample WTX Action Exit is made up of four Java classes:
-
WTXTransformationFactory: This is the Action Handler class that is invoked by Partner Gateway. It retrieves the Action Handler Configuration and the business document from Partner Gateway and then invokes WTXProcess to transform the document using Transformation Extender.
-
WTXProcess: This class determines the locations of the input and output files and the name and location of the WTX map executable file and then invokes either the WTXProcessRMI class or the WTXProcessLocal class to invoke Transformation Extender and perform the transformation.
-
WTXProcessRMI: This class invokes Transformation Extender using the Transformation Extender Java RMI APIs.
-
WTXProcessLocal: This class invokes Transformation Extender using the Transformation Extender Java JNI APIs.
You only need to configure one WTX Action Exit in Partner Gateway regardless of the number of different maps as the relationship between WTX Action Exit and Transformation Extender Maps is one-to-many (a single instance of the WTX Action Exit can invoke many different Transformation Extender maps).
The Action Handler Configuration values that are required by the WTXProcess, WTXProcessRMI and WTXProcessLocal classes are set on the Action Handler itself in the Partner Gateway Console (shown in Figure 7).
Figure 7. WTX Action Handler Configuration
The WTXProcess class uses the WTX_RMIServer_Use_Server flag to determine whether to invoke the WTXProcessRMI (yes) or the WTXProcessLocal (no) class to perform the transformation. If the WTXProcessRMI class is to be used, the values for the hostname (WTX_RMIServer_Hostname) and port (WTX_RMIServer_Port) are used to establish a connection to the Transformation Extender RMI Server. The location of the WTX Map executable file is required for both JNI and RMI connections and is specified in the WTX_Map_Root configuration parameter.
Map specific configuration values are provided in a Map Configuration File that is uploaded to Partner Gateway using the Partner Gateway Console. The values that can be found in the map configuration file are:
-
WTX_MAP_NAME: This value specifies the name of the map executable file relative to the WTX_Map_Root configuration value.
-
WTX_OUTPUT: This value specifies whether or not output is expected from the map. This value is set to NONE when a validation only map is being invoked.
When an instance of the WTX Action Exit is processing a document, it performs the following steps:
- Get the required configuration values from the WTX Action Handler Configuration.
-
WTX_Map_Root: This value points to a directory that can contain a number of executable map files.
-
WTX_RMIServer_Hostname: This value is only used when the WTX Action Exit is running in RMI mode.
-
WTX_RMIServer_Port: This value is only used when the WTX Action Exit is running in RMI mode.
- Get the required configuration values from the Map Configuration File.
-
WTX_MAP_NAME: This value is used to identify the specific map.
- Generate the fully qualified file name of the WTX Map that is going to be executed by Transformation Extender.
- Get the fully qualified file name of the file containing the document to be transformed from the Partner Gateway Business Document Instance.
- Create a new WTX Map Object using the required parameters.
-
JNI: Create a new com.ibm.websphere.dtx.dtxpi.MMap object using the fully qualified name of the WTX Map to be invoked.
-
RMI: Create a new com.ibm.websphere.dtx.dtxpi.rmi.IMFactory object using the hostname and port of the Transformation Extender RMI Server and then create a new com.ibm.websphere.dtx.dtxpi.rmi.IMMap object using the fully qualified name of the Transformation Extender Map to be invoked.
- Modify the Input Card of the Map to use the fully qualified file name of the file containing to be transformed.
- Use MCard inputCard = map.getInputCardObject(1) to get the Input Card of the Map.
- Use MAdapter inputAdapter = inputCard.getAdapter() to get the File Adapter for the Input Card.
- Create a new XML string that contains the fully qualified file name of the file containing to be transformed.
- Set the Properties of the File Adapter to the new XML string by using inputAdapter.setPropertiesXML(xml)
- Modify the Output Card of the Map to use the fully qualified file name of the file that will contain the transformed document.
- Use MCard outputCard = map.getOutputCardObject(1) to get the Output Card of the Map.
- Use MAdapter outputAdapter = outputCard.getAdapter() to get the File Adapter for the Output Card.
- Create a new XML string that contains the fully qualified file name of the file that will contain the transformed document.
- Set the Properties of the File Adapter to the new XML string by using outputAdapter.setPropertiesXML(xml)
- Run the Map using map.run();
- Validate the Map Response Message and Result Code to ensure that the transformation was successful.
- If the transformation was unsuccessful, return an error containing the Map Response Message and Result Code.
- If the transformation was successful, set the file that contains transformed document as the document to be delivered to the trading partner.
The sample WTX Action Exit is fully functional and comes packaged with an example Transformation Extender Map and input files to give anyone attempting a Partner Gateway and Transformation Extender integration a head start.
Conclusion
This article introduced you to Transformation Extender and described how Partner Gateway processes a document from receipt to delivery to the destination. It outlined the available Partner Gateway and Transformation Extender integration patterns and covers the Java JNI and RMI patterns in depth. You should now have the required information to integrate Partner Gateway and Transformation Extender using either the Java JNI or the Java RMI patterns.
Resources
About the author  | | |
Dave Mulley is an IT Specialist and a member of the IBM Software Services for WebSphere Enablement team based in Raleigh, North Carolina. Dave is focused on the WebSphere Business Integration family of products and has worked for IBM since 1999. You can reach Dave at dmulley@us.ibm.com
|
Rate this page
| 
