Calling WebSphere Transformation Extender maps from WebSphere Cast Iron Cloud Integration

This article shows you how to call WebSphere Transformation Extender(TX) maps from WebSphere Cast Iron orchestrations as services. Includes source code for a sample TX Web service.

Michael Hudson (mhudson@us.ibm.com), Senior Technical Staff Member, Data Transformation Strategy and Architecture, IBM

Photo of Michael HudsonMichael Hudson is the IBM Senior Technical Staff Member (STSM) for WebSphere Transformation Extender products at the IBM Software Lab in Boca Raton, Florida. You can contact Michael at mhudson@us.ibm.com.



07 September 2011

Also available in Chinese

Introduction

IBM® WebSphere® Transformation Extender, formerly called IBM DataStage TX and hereafter referred to as WebSphere TX, was first introduced in 2005. WebSphere TX maps provide complex, any-to-any and many-to-many transformation capabilities that can be executed either standalone or embedded into other IBM products, such as WebSphere Message Broker, WebSphere ESB, and WebSphere DataPower SOA Appliances.

In 2010, IBM acquired Cast Iron Systems and began to offer clients an end-to-end platform to integrate cloud applications from providers such as ADP, Amazon, NetSuite, and Salesforce.com, with on-premise applications from providers like JD Edwards and SAP. By using Cast Iron's hundreds of pre-built templates, you can eliminate expensive custom coding and complete enterprise cloud integrations in the space of days instead of the usual weeks or months. You can achieve these results using a physical appliance, a virtual appliance, or a cloud service.

Cast Iron includes built-in support for XSLT to support XML transformations, and it provides integration between various cloud services providers through its support for Web services. This article describes one way to extend Cast Iron's built in transformation capabilities beyond simple XML transforms, by calling WebSphere TX maps and exposing them to the cloud as Web services.

Prerequisites

This article assumes that you have WebSphere TX V8.3, WebSphere Cast Iron Studio V6.0, WebSphere Application Server V7, and WebSphere Integration Developer V7. It also assumes that you have a basic understanding of WebSphere TX and that you know how to create a simple WebSphere TX map with one input and one output card.

Hosting a WebSphere TX map as a Web service

WebSphere TX provides a Software Development Kit (SDK) that includes a Java API. Starting with WebSphere TX V8.3, the SDK is bundled with Design Studio. The Java API enables any Java program to create objects representing WebSphere TX maps, configure them, and run them.

The first step in this process is to create a WebSphere TX map. You can use one of the example maps that come with Design Studio, such as the states map, which rearranges statistics on US states. It is located in the Design Studio directory under examples\general\states.

  1. Open the states.mms file in Design Studio and build the map called master to generate an executable map called master.mmc. You can test the map by running it in Design Studio. It should read the input file sts.txt and generate an output file output.txt that looks like this:
    OH,257*IN,142*MI,154*WI,80*MT,5*ID,8*WY,3*CO,21*NM,
    8*AZ,15*UT,13*NV,4*MN,48*MO,67*ND,9*SD,9*KS,27
  2. You need to make one small modification to this map to make it Web service friendly. Open the states.mtt type tree and locate the United States group under the Input category. Then open its properties and change the Group Subclass / Format / Component Syntax / Delimiter / Value to <LF>. This change prevents the map from running in Design Studio, but don't worry; it will make for a good Web service.
    Figure 1. Changing the delimiter
    Changing the delimiter
  3. Analyze and save the type tree then rebuild the map to generate a new master.mmc executable map.
  4. In order to run this map from a Cast Iron Orchestration, you must first expose it as a Web service. There are numerous ways to expose maps as Web services. A simple way is to use IBM Integration Developer (formerly known as WebSphere Integration Developer), which provides a simple wizard for generating a Web service from a Java class. Since WebSphere TX provides a Java API, there is a good fit. Open the Web perspective in IBM Integration Developer and create a new Dynamic Web Project. Name the project and then click Finish:
    Figure 2. Creating a dynamic Web project
    Creating a dynamic Web project
  5. Next, you need to write Java code to invoke the WebSphere TX map before it can be turned into a Web service. Before you can do that, make sure that the project understands the WebSphere TX Java API. Open the project's properties, navigate to Java Build Path and add dtxpi.jar (located in your Design Studio or in the WebSphere TX installation directory) as an external JAR:
    Figure 3. Configuring the Java build path
    Configuring the Java build path
  6. Create a new Java Class in your new project, name it, and click Finish:
    Figure 4. Creating a Java class
    Creating a Java class
  7. You will be presented with an empty Java class in the main editor. Fortunately, you do not have much code to write and you can use one of the WebSphere TX SDK examples as a starting point. Open Example5.java in a text editor -- it is located in the examples\dk\dtxpi\java directory under your Design Studio installation.
  8. Copy and paste the import statements into your new Java class:
    import com.ibm.websphere.dtx.dtxpi.MAdapter;
    import com.ibm.websphere.dtx.dtxpi.MCard;
    import com.ibm.websphere.dtx.dtxpi.MConstants;
    import com.ibm.websphere.dtx.dtxpi.MMap;
    import com.ibm.websphere.dtx.dtxpi.MStream;
    import com.ibm.websphere.dtx.dtxpi.MException;
  9. Copy and paste the main() method into your new Java class, and change its signature to public String runMap(String szInputBuffer).
  10. You will pass the input buffer in with each call to the Web service, so the static definition of szInputBuffer must be removed: //private static String szInputBuffer = "This is my input data";.
  11. Since this class will be invoked repeatedly, move the code that initializes the WebSphere TX API into a static block:
    static
    {
       try
       {
          MMap.initializeAPI(null);
       }
       catch (Throwable t)
       {
          t.printStackTrace();
       }
    }
  12. You must also remove or comment out the line of code that terminates the WebSphere TX API: //MMap.terminateAPI();
  13. The states map only has one output card, so modify the line of code that looks for the output card to point to output card 1 instead of card 2: card = map.getOutputCardObject(1);
  14. Create a new String to hold the output from the map: String outData = "";.
  15. Change the comment telling you to do something with the data produced by the map, to a line of code that appends each page to the output String: outData += new String(page);
  16. Make your runMap method return the output String: return outData;
  17. Finally, change the name of the map to point to the master.mmc file you built in Design Studio:
    MMap map = new MMap("C:\\IBM\\WebSphere Transformation Extender 8.3
       \\examples\\general\\states\\master.mmc");
  18. You should now have a Java class that builds without error. If you don't, don't worry because one is attached to this article.
  19. Create a new Web service in your new project. To open the Web Service wizard, select File => New => Other/Web Services:
    Figure 5. Finding the Web service wizard
    Finding the Web service wizard
  20. You need a bottom-up Java bean Web service, and you should specify your Java class as the service implementation:
    Figure 6. Running the Web service wizard
    Running the Web service wizard
  21. Click Next and accept all of the defaults on the following screens. You should now have a Web service, and you may (depending on your IBM Integration Developer configuration) have deployed it already. If it is not deployed, then log on to WebSphere Application Server and deploy the EAR manually.
  22. You can test the Web service using the IBM Integration Developer Web Services Explorer. The argument to the szInputBuffer parameter is the contents of the sts.txt file in the folder where your states map is located.

Importing the WSDL into WebSphere Cast Iron Studio

  1. The Web service wizard you ran in IBM Integration Developer created a WSDL definition file. You can locate it in your project under WebContent/WEB-INF/wsdl. This file can be imported into a new WebSphere Cast Iron Studio project.
  2. Open WebSphere Cast Iron Studio and create a new project. From the Project tab, right-click on WSDLs and select Add Document. Browse for your WSDL file and click OK:
    Figure 7. Import the WSDL
    Import the WSDL

Creating the orchestration

Create an orchestration to invoke this Web service. You can use any endpoints, but for simplicity, use HTTP endpoints:

  1. From the Activities tab, drag an HTTP Receive Request activity onto the orchestration. Drag an HTTP Send Response activity on the orchestration and drop it to the right of the Receive Request.
  2. Select the Receive Request and click on it to open its configuration. In the checklist, select Pick Endpoint and click New. Choose a port number and click OK. Again, in the check list, select Configure and choose a URL , such as /runthemap. Leave the message type as Text and check Requires a Reply:
    Figure 8. Configuring the Receive Request activity
    Configuring the Recieve Request activity
  3. Select the Send Response activity and click on it to open its configuration. Notice that when you select Configure in the checklist, the Reply To already shows Receive Request and the message type is already Text.
    Figure 9. Configuring the Send Response activity
    Configuring the Send Response activity
  4. From the Activities tab, drag a Web Services / Invoke Service activity onto the orchestration and drop it between the Receive Request and Send Response activities:
    Figure 10. Adding the Invoke Service activity
    Adding the Invoke Service activity
  5. Select it to open its configuration. In the checklist, select Pick Endpoint and click New. Click Browse next to the WSDL Name field and browse for the WSDL you imported. Click OK and then OK again.
  6. All that remains now is to map the variables through Cast Iron. Starting on the left, click the Receive Request activity and in the checklist click Map Outputs. Locate the body, select it, and click Copy. Select Body from the output parameters and choose Create:
    Figure 11. Mapping outputs from Receive Request activity
    Mapping outputs from Receive Request activity
  7. Select the Invoke Service activity and in its checklist select Map Inputs. Click Select Inputs and choose body. Map the body to the szInputBuffer:
    Figure 12. Mapping inputs to the Invoke Service activity
    Mapping inputs to the Invoke Service activity
  8. From the checklist, select Map Outputs, then click Select Outputs, and choose body. Map runMapReturn to the body:
    Figure 13. Mapping outputs from the Invoke Service activity
    Mapping outputs from the Invoke Service activity
  9. Select the Send Response activity, open its configuration, and from the checklist select Map Inputs. Click Select Inputs and choose body. Map the input body to the output body:
    Figure 14. Mapping inputs to the Send Response activity
    Mapping inputs to the Send Response activity
  10. Save the project.

Testing the orchestration

  1. The easiest way to test your new orchestration is to run it inside Cast Iron Studio. To do this, click the Verify tab and then click the green triangle to start the orchestration:
    Figure 15. Verifying the orchestration
    Verifying the orchestration
  2. From the Tools menu, open the HTTP Post Test Utility and specify your URL. If you do not know your host name, you can find it by looking in the Cast Iron error log. The port and the path are the ones you specified above. Click Show Response and paste the contents of the sts.txt file (from the states example in Design Studio) into the Message to post text box. Click Submit to send the data to the orchestration. You should see the output from the map in the response window:
    Figure 16. The HTTP Post utility
    HTTP Post utility

Conclusion

This article showed you how to create a Web service that calls the WebSphere TX Java API to run a map. You created a Cast Iron orchestration that uses the Invoke Service activity to call this Web service, thereby running a map. Although this article used a simple example map, a simple example of the Java API, and a simple orchestration, you can extend the concepts to any WebSphere TX map hosted in any Web services container and called from any Cast Iron orchestration.


Download

DescriptionNameSize
Code sampleCastIronArticleImpl.zip2 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

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

 


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

All information submitted is secure.

Choose your display name



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

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

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=756177
ArticleTitle=Calling WebSphere Transformation Extender maps from WebSphere Cast Iron Cloud Integration
publish-date=09072011