Originally posted by: PaulBrettIBM

I found this (now archived) article written by Nidhi Nijhawan (nidhinijhawan@in.ibm.com) and decided to re-publish it here, as it is a good summary of the process.

This article shows you how to create type trees and maps using WebSphere Transformation Extender (WebSphere TX) Design Studio, how to create process flows and the executable systems of maps using WebSphere TX Integration Flow Designer, and how to deploy maps as executable systems using WebSphere TX Launcher.

Introduction

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.

1. Open the WebSphere TX Design Studio and select a workspace.
2. In the Transformation Extender Development perspective, create a new Extender project. Enter the project name as SupplyChain and click Finish.
3. Right-click on the TypeTrees folder under the SupplyChain project, and select New => Type Tree:
4. Select SupplyChain as the parent folder and name the TypeTree Order_CSV.
5. 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.
6. Modify the properties of the Root type. Change the name of the type from Root to Data and press Enter:
7. 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.
8. 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.
9. Similarly, create a category for Groups.
10. 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 appropriate properties.
11. 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 number based properties.
12. 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.
13. 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.
14. Add another group called File under the Groups category.
15. 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.

Developing the output type tree for the Order map

1. Right-click on TypeTrees in the Extender Project and select Import => XMLSchema.
2. Select Order.xsd in the XML Schema Importer window and click Next.
3. Select the Parent project and click Finish to generate the type tree, which is named Order.mtt.

Developing the Order map

1. Right-click on the Map Files folder in the Extender Project and select New => Map Source.
2. Give the name as SupplyChain.
3. In the Outline view, right-click on the Map Source and select New.
4. Give the name of the map as Order.
5. Right-click on the input cards and select New. Enter the values.
6. Right-click on the output cards and select New. Enter the values.
7. 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.
8. 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.
9. 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 and then press Enter.
10. Save the map.
11. Right-click on the Order map and select Build. Check the Build Results view to see if there are any errors.
12. When the build is successful, right-click on the Order map and select Run.
13. 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>
    

14. 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.
15. Create the functional map F_OrdertoShipping using the Functional Map Wizard and populate the map rules.
16. 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:

1. 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.
2. From the menu, select System => Add Component => Source Map.
3. 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.
4. Double-click on the maps to open up the input and output cards.
5. 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.
6. 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.
7. 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.
8. After you have turned on the Source Event, you will see a pair of glasses watching for an event.
9. 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.

1. To deploy the map, select System => Deploy => Definitions. Name it SupplyChain.
2. Highlight Generate and Transfer Launcher Control File, and click Details.
3. 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.
4. Close the Define Deploy Scripts window.
5. To deploy the definition to the Launcher runtime, select System => Deploy => SupplyChain.
6. If the deployment is successful, you will see the message "The deploy operation has completed successfully.
7. Click Yes on the pop-up window to view the results.
8. 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.
9. 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.

 

Thank you.

Paul

Follow me on Twitter

#IBMSterlingTransformationExtender
#DataExchange
#IBM-Websphere-Transformation-Extender