Developing and deploying transformations using WebSphere TX Design Studio, Integration Flow Designer, and Launcher
IBM® WebSphere® Transformation Extender (hereafter called WebSphere TX) is a powerful, transaction-oriented universal data transformation and validation solution that automates the transformation and routing of high-volume data from source systems to target systems in both batch and real-time environments. It handles data in any format -- XML, non-XML, or mixed. This article describes WebSphere TX Design Studio, Integration Flow Designer, and Launcher, and shows you how to implement a supply chain scenario.
In this scenario, when an order is received, if the quantity requested is 100 or higher, OrderStatus is set to Unavailable, and if it is below 100, OrderStatus is set to Available. This message is passed on to the shipping department, which checks OrderStatus. If it is Available, then the shipping status is updated to Shipped, otherwise it is set to Rejected. In the following sections, you will see how to implement this solution using:
- WebSphere Transformation Extender Design Studio to develop and test maps
- WebSphere Transformation Extender Integration Flow Designer to develop a system of maps
- WebSphere Transformation Extender Launcher to deploy the systems developed in Integration Flow Designer
Developing type trees and maps using WebSphere TX Design Studio
To implement the above scenario, you need to develop two maps -- Order and Shipping. Order map takes input in the form of flat files and transforms them to XML. The Shipping map takes the output XML from Order map and transforms it to another XML file with the Shipping information. To begin with, you need to develop the type trees required for these two maps.
Developing the input type tree for the Order map
The input to the Order map is in comma separated format. Each input file has many Order records, each of which consists of the following fields: Catalog Number, Contact Address, Contact Name, CustomerID, OrderDate, OrderNumber, QtyOrdered, UnitPrice, and WantDate.
- Open the WebSphere TX Design Studio and select a workspace.
- In the Transformation Extender Development perspective, create a new Extender project. Enter the project name as SupplyChain and click Finish.
- Right-click on the TypeTrees folder under the SupplyChain project, and select New => Type Tree:
Figure 1. Creating new type tree
- Select SupplyChain as the parent folder and name the TypeTree Order_CSV.
- After the type tree has been built, you will be prompted to open the type tree. An empty type tree will open up in the editor and at the bottom of the page, you will see the Extender Properties view, which shows the properties of a particular data type. Select Root and click on the Extender Properties View.
- Modify the properties of the Root type. Change the name of the type from Root to Data and press Enter:
Figure 2. Type tree designer window
- Right-click on Data and select Add to add the other data types. Click Yes in the pop-up window to create a new data type.
- In the Extender Properties view, change the name of the data type to Element and press Enter. Under this category, you will create all of the item-level data types.
- Similarly, create a category for Groups.
- Start adding the fields under the Element category in a similar way. The Class property must be changed from Category to Item. The Catalog Number element is in Text format. Choose the properties as shown below:
Figure 3. Catalog Number properties
- Similarly, create the other text fields: Contact Address, Contact Name, CustomerID, and OrderNumber.
Add the QtyOrdered and UnitPrice fields under the Element category. These fields are of Number format, so choose the properties as shown below:
Figure 4. QtyOrdered Properties
- Add the OrderDate and WantDate fields under the Element category. These fields are of Date format, so specify the Item subclass as Date && Time and leave other properties as default.
- Create groups for the Order record and the entire file, which has multiple Order records. Add a group called Record under the Groups category. Select the Class property as Group.
Each Order record consists of fields separated by commas, so this group is defined as Explicit -- Delimited and the delimiter value is "," . Each record is terminated by newline character:
Figure 5. Record Group properties
- Add another group called File under the Groups category.
- Since the Record is an explicitly defined group, the File will be an implicit group. So change the class to Group and leave other properties as default. The type tree definition is now complete:
Figure 6. Completed type tree view
Developing the output type tree for the Order map
Download the Order.xsd file at the bottom of the article if you have not already done so and use it to create the output type tree:
- Right-click on TypeTrees in the Extender Project and select Import => XMLSchema.
- Select Order.xsd in the XML Schema Importer window and click Next.
- Select the Parent project and click Finish to generate the type tree, which is named Order.mtt.
Figure 7. Order Type Tree generated from XSD
Developing the Order map
- Right-click on the Map Files folder in the Extender Project and select New => Map Source.
- Give the name as SupplyChain.
- In the Outline view, right-click on the Map Source and select New:
Figure 8. Creating new map
- Give the name of the map as Order.
- Right-click on the input cards and select New. Enter the values as shown below and click OK:
Figure 9. Input card properties for Order Type Tree
- Right-click on the output cards and select New. Enter the values as shown below and click OK:
Figure 10. Output card properties for Order Type Tree
- The map will open in the Toolkit. Populate the fields in the output tree as shown below. Enter each value in the Rule Editor and press Enter. The value will be added in the Output Card field.
For the entry F_OrderCSVtoXML(Record:CSVinput), write the name of the functional map as F_OrderCSVtoXML() in the Rule Editor.
Drag and drop the Records field from the input card in the braces and press Enter:
Figure 11. Mapping the fields in Order map
- F_OrderCSVtoXML is a functional map, which is like a subroutine, and will be executed for mapping each record in the input file one-by-one.
Right-click on F_OrderCSVtoXML and select Functional Map Wizard. In the wizard, click Create:
Figure 12. Functional map wizard
- Map the fields in the functional map. Drag and drop each field in the input card onto the respective field in the output card. For the OrderStatus variable, there is simple logic
to check if the ordered quantity is less than 100. Add the rule to the Rule Editor as shown below and then press Enter:
Figure 13. Adding rules for the fields in Order map
- Save the map. The map outline should look like this:
Figure 14. Map outline view
- Right-click on the Order map and select Build. Check the Build Results view to see if there are any errors.
- When the build is successful, right-click on the Order map and select Run. If the run is successful, the following window will pop up:
Figure 15. Map execution successful
- Under the Misc folder in the Extender project, open the output file XMLOut.txt. If the file has records in XML format as shown below, the map has executed successfully:
<Order> <OrderNumber>ABC123</OrderNumber> <CustomerID>CUST01</CustomerID> <ContactName>DeviPriya</ContactName> <ContactAddress>XYZ Street Bangalore</ContactAddress> <OrderDate>2009-07-07</OrderDate> <WantDate>2009-10-07</WantDate> <CatalogNumber>123</CatalogNumber> <QtyOrdered>50</QtyOrdered> <UnitPrice>10</UnitPrice> <OrderStatus>AVAILABLE</OrderStatus> </Order>
- You need to create another map named Shipping. Import the Shipping.xsd file provided in the downloadable artifacts.zip file. Create a type tree out of the .xsd file using the instructions above.
Create a map named Shipping. The input card to this will refer to the Order type tree and the output card will refer to the Shipping type tree. In the input card for Get => Source => File Path,
enter the file name as XMLOut.txt. For the output card, enter the file name as ShippingXML.txt. The main map will look like this:
Figure 16. Shipping map view in map designer
- Create the functional map F_OrdertoShipping using the Functional Map Wizard and populate the map rules as shown below:
Figure 17. Functional map referenced from Shipping map
- Build and run the Shipping map. The output of the Order map XMLOut.txt is the input to the Shipping map. Since the Order map has been run successfully, XMLOut.txt will be present in the workspace.
When you run the Shipping map, XMLOut.txt will be the input to the map and the output generated will be ShippingXML.txt. Verify that it is similar to this:
<Shipping> <OrderNumber>ABC123</OrderNumber> <CustomerID>CUST01</CustomerID> <ContactName>DeviPriya</ContactName> <ContactAddress>XYZ Street Bangalore</ContactAddress> <OrderDate>2009-07-07</OrderDate> <ShippingDate>2009-10-28</ShippingDate> <CatalogNumber>123</CatalogNumber> <QtyOrdered>50</QtyOrdered> <UnitPrice>10</UnitPrice> <ShippingStatus>SHIPPED</ShippingStatus> </Shipping>
Developing a system of maps using WebSphere TX Integration Flow Designer
WebSphere TX Integration Flow Designer helps you create visual process flows, and from them create executable systems that are processed by the Launcher or Command Server. It enables you to easily manage collections of related maps by graphically organizing them into logical collections of systems. The graphical representation of systems in the Integration Flow Designer helps to visualize system designs, what-if scenarios, and system execution behavior. In this section, you will develop a system of maps that you have already created, and then deploy the executable system in WebSphere Transformation Extender Launcher:
- Open the Integration Flow Designer GUI: Select Start => WebSphere Transformation Extender V8.2 => Design Studio => Integration Flow Designer. Select Create a new system definition file.
- From the menu, select System => Add Component => Source Map:
Figure 18. Adding source map
- Browse and select the source map name from the workspace path. The maps in the map source will be listed. Select both of the maps to create the System. Sometimes the Order map is hiding under the Shipping map on the canvas, so you will need to drag the Shipping map to see the Order map.
- Double-click on the maps to open up the input and output cards:
Figure 19. Maps in Integration Flow Designer
- Verify the location of the input files, output files, and schema files. If the file locations are correct, you will see connectivity between the maps.
If not, give the absolute path reference for the files by double-clicking the input and output files:
Figure 20. Launcher settings
- The output file of Order map is the input file to Shipping map. After the file paths have been corrected, you will see the connectivity between the maps as shown below.
If you change any parameter in this setting, it will override the map setting.
Figure 21. System created in Integration Flow Designer
- Right-click on the map and select Edit Launcher. The window shown below in Figure 22 will open. Expand the inputs and change Source Event from OFF to ON,
to signal the Launcher to run the map when the input file arrives in the specified directory. Click OK.
Figure 22. Editing Launcher settings
- After you have turned on the Source Event, you will see a pair of glasses watching for an event.
- Select LocalServer as the Server and Execution Mode as the Launcher. Save the System definition file.
Deploying system of maps using WebSphere TX Launcher
WebSphere TX with Launcher provides a standalone event server to host the WebSphere TX engine. It includes the command-line and script processing capabilities and activates transformations when triggered by an event, such as a file creation, a message arriving on a WebSphere MQ queue, a database trigger, a scheduler, or a combination of different triggers. The Launcher offers an online run-time environment that synchronizes and controls complicated data transformations while maintaining and optimizing the execution environment for the transformations. This section shows you how use the WebSphere TX Launcher to deploy the executable system that you developed in the Integration Flow Designer.
- To deploy the map, select System => Deploy => Definitions. Name it SupplyChain:
Figure 23. Editing deploy definitions
- Highlight Generate and Transfer Launcher Control File, and click Details:
Figure 24. Editing deploy definitions
- Select the WebSphere TX installation directory /Systems and save the deploy scripts with the name SupplyChain.msl. You must save the .msl file in /Systems so that the Launcher can find it.
- Close the Define Deploy Scripts window.
- To deploy the definition to the Launcher runtime, select System => Deploy => SupplyChain.
- If the deployment is successful, you will see the message "The deploy operation has completed successfully.
- Click Yes on the pop-up window to view the results, which should look like this:
Figure 25. Results of successful deploy
- Start the service IBM WTX Launcher. If it is already started, stop and restart it. When you deploy a new system file, you must restart the Launcher.
Figure 26. IBM WebSphere TX Launcher service
- The input file is already available in the input file location. After the Launcher has restarted, check the directories C:\\Documents and Settings\\Administrator\\IBM\\wtx\\devworks\\SupplyChain\, (or wherever you have configured the output to be written to) for the output files. If the Launcher has run the maps and generated the output files, you should see XMLOut.txt and ShippingXML.txt. If the files are not there, check that the input file and schema files are in the correct locations, and that the system has the correct absolute path reference to their locations.
This article has shown you how to:
- Develop and test maps using WebSphere TX Design Studio.
- Develop a system of maps using WebSphere TX Integration Flow Designer.
- Deploy the systems using WebSphere TX Launcher.
- WebSphere Transformation Extender information center
A single Web portal to all WebSphere Transformation Extender documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere Transformation Extender.
- WebSphere Transformation Extender product page
Product descriptions, product news, training information, support information, and more.
- WebSphere Transformation Extender requirements
Hardware and software requirements for WebSphere Transformation Extender.
- WebSphere Transformation Extender support
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- IBM Tivoli Composite Application Manager System Edition (ITCAM SE) for WebSphere DataPower product page
Product information, downloads, and support
- IBM Tivoli Monitoring information center
A single Web portal to information on deploying, installing, and configuring the common services components and the monitoring agents that make up the base Tivoli Monitoring product.
- IBM Tivoli Composite Application Manager for SOA information center
A single Web portal to information on Tivoli Composite Application Manager for SOA.
- IBM Tivoli Composite Application Manager for SOA, V6.1 User's Guide
A single Web portal to information on installing, configuring, and using Tivoli Composite Application Manager for SOA, V6.1 to monitor Web services on AIX, z/OS, Linux, Solaris, and Windows.
- developerWorks WebSphere application connectivity developer resources
How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
- developerWorks WebSphere business process management developer resources
WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
- developerWorks WebSphere SOA and Web services developer resources
How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
- developerWorks blogs
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks on Twitter Check out recent Twitter messages and URLs.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere on-demand demos
Download, watch, and learn what WebSphere products and WebSphere-related technologies can do for your company.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.