Integrating applications using WebSphere Business Integration Message Broker V5

Part 1: Integration scenario Creating a Web order processing application

Introduction ...........................................................................................................1
Integration scenario....................................................................................................... 2

Creating a Web order processing application .......................................................4

Message flow: ProcessPurchaseOrder........................................................................ 5 Flow walk through ......................................................................................................... 5 Message processing nodes used in ProcessPurchaseOrder Flow............................... 7 Aggregate Node Family .............................................................................................. 11

Summary ............................................................................................................19 Appendix A .........................................................................................................20 Instructions for setting up Web Order Sample ....................................................20
Pre-requisites: WBIMB Service Pack2....................................................................... 20

References .........................................................................................................28 About the author .................................................................................................28

Introduction
This is the first article in a six-part series on WebSphere Business Integration Message Broker V5. WebSphere Business Integration Message Broker plays a critical role in enterprise computing by integrating disparate applications without making any changes to the applications. Integration is achieved by sending a message in the format expected by an application. The response received from it is converted to the format needed by the other application. WebSphere Business Integration Message Broker provides such message brokering and transformation capability. The WebSphere Business Integration Message Broker V5 tooling stack has been significantly enhanced and is based on the Eclipse platform. Through this series of articles, we will illustrate the new tooling features of WebSphere Business Integration Message Broker V5 by providing the information you need to build, deploy, debug, and run a Web Order Processing Application sample. This article illustrates how WebSphere Business Integration Message Broker is used to integrate applications running on backend systems. It describes an integration scenario that builds an automated Web order processing application using existing data and applications running on backend systems. The article then introduces you to the concept of message flows and provides a description of the flows and sub flows used in creating this application. Finally, it provides a detailed walk through of the main Web order processing flow and describes in detail the IBM supplied message processing nodes used in building this flow.

Given below is a high-level overview of the other upcoming articles in this series: Part 2: Message Set Development using WebSphere Business Integration Message Broker This article describes the concept of message sets, logical and physical representation of messages. It describes how to create messages used in the integration sample from XML Schema, COBOL copy book and the modification and maintenance of messages using the spread sheet like message editor. Part 3: Developing Message Flow Applications using WebSphere Business Integration Message Broker This article describes the concept of message flow schemas and the tools to build and maintain message flows used in the integration sample. It describes how to use ESQL (enhanced SQL language with message specific modifications) to manipulate the contents of message instances used in the flow. Part 4: Message Transformation using WebSphere Business Integration Message Broker mappings This article describes the message transformation capabilities of WebSphere Business Integration Message Broker. It describes the message to message, message to database, database to message mapping and transformations used in the integration sample. Part 5: Custom Message Flow Node Development using WebSphere Business Integration Message Broker This article describes how to build a custom message flow node which, like any of the IBM supplied message flow node, can be used in a message flow. It describes the steps to build SendMail message node using JavaMail APIs to send email messages. This node is used in the Web order processing application sample to send order confirmation / rejection message to the customer. Part 6: Debugging WebSphere Business Integration Message Broker Message Flows This article describes how to deploy and debug the message flows in WebSphere Business Integration Message Broker using the Web order processing application sample as an example.

Integration scenario
This section provides the background information you need to create a new automated Web order processing application and a brief description of the applications systems that are loosely integrated using message broker. . XYZ Parts Inc. maintains its customers, suppliers, and parts price database in DB2 and parts inventory in online transaction processing systems, such as CICS. An XYZ sales representative receives orders via phone or mail and processes the orders by extracting customer information from DB2. The sales representative checks whether the requested parts are in stock (for example, using a 3270 terminal attached to a CICS sub system), calls the credit card processing center to get authorization for the purchase amount, and then sends a confirmation or rejection response to the customer via phone or mail. Now, XYZ Parts Inc. has decided to fully automate the order processing system and sell the parts directly to customers over the Web. Instead of writing this new application from scratch, it wants to leverage its existing assets by reusing its inventory control systems and customer, supplier and parts price databases in DB2.

Figure 1 shows how the application systems will be connected with WebShere Business Integration Message Broker through WebSphere MQ and the format of the messages that will be exchanged between message broker and the application systems. Under the new system, the customer sends an order request over the Web in XML format; the structure and contents of which is defined by XML schema. The Web server receives the request and sends it to a WebSphere MQ queue for processing. The Web Order Processing application running in the message broker picks up the request and interacts directly with the DB2 database to extract customer information and order items prices. It then computes the total price of the purchase order and sends messages to the: a) Inventory Control System to query if the requested parts are in stock. The structure and format of this message is CWF (Custom Wire Format), which are typically the bits and bytes as defined by the structure of a COBOL copy book or C structure. b) Credit Card Processing System to get approval for the purchase amount. The structure and format of this message is TDS (Tagged Delimited String). TDS format for messages is predominantly used by banking and financial applications and by most of the industrystandard message sets such as SWIFT and EDIFACT, X12, and so forth.

Application Integration using Message Broker

Web Order Processing
DB2
Q W eb
XML Message TDS Message

Sp

he

re

WBIMB
WebSphere MQ

Message Broker
WebSphere MQ

WebSphere MQ

Web Server

Internet Internet

Credit Card Processing System

XML Message

CWF Message

Supplier System

Mail Server
Inventory Control system

Figure 1 : Application integration using WebSphere Business Integration Message Broker.

When the Web Order Processing application receives the responses from the Inventory Control System (in CWF format) and Credit Card Processing System (in TDS format), it will: o o Send an order confirmation or rejection notification to the customer by email depending upon the status of credit approval. Accept the order if the credit approval is okay. The Web Order Processing application will then send a message to the Inventory Control System to update the inventory. If the Web Order Processing application determines during the process that the part quantity in stock has gone below a threshold value, then it will create and send a message to the supplier in XML format to replenish the stock.

Instructions for installing and running the Web Order sample are included in Appendix A.

Creating a Web order processing application

This section provides a brief introduction to WebSphere Business Integration Message Broker message flows and sub flows. It then describes the ProcessPurchaseOrder flow in details which is the main message flow that implements the Web Order Processing application in the message broker.

Message flow
A message flow consists of a number of message processing nodes that are wired together to build a WebSphere Business Integration Message Broker application. Each node has one or more input and/or output terminals. Each node exposes a set of properties that can be set by the users to define parameters to the flow application. Users can associate ESQL (SQL language with specific extensions for message processing) code with some of these nodes (for example, compute node) to manipulate the contents of database and/or the message. Like most fourth generation programming languages, ESQL can be used to develop business logic but it is typically used to select and analyze the message and/or database contents and perform complex conversions of data values using ESQL library routines or ESQL expressions. WebSphere Business Integration Message Broker supplies a rich set of built-in message-processing nodes to build a flow application very quickly.

Sub flow
In traditional programming languages, subroutines are used to group commonly used statements. With WebSphere Business Integration Message Broker, this is achieved using sub flows. The sub flows are comprised of the same nodes as the main line flows except that they have input and output terminals nodes. These nodes are added to the sub flow to define the input and output terminals. Main message flows or higher level sub flows simply include the desired sub flow as if it were another node and wire up its terminals accordingly. This technique is very powerful for building very complex message flows as it structures the flow into a series of smaller and more readable sub flows. Apart from code reuse, the use of sub flows significantly improves readability of the flow logic.

Message flow: ProcessPurchaseOrder

ProcessPurchaseOrder flow shown in Figure 2 is the main flow which processes the order request. In this flow we have tried to use most of the WebSphere Business Integration Message Broker supplied built-in nodes to show the product functionality. We have used a number of sub flows to break down and manage the tasks in sizable chunks and most importantly to improve the readability of the flow.

Flow walk through

ProcessPurchaseOrder flow receives the order request from MQInput node ORDER.REQUEST.Q001 and using the Filter node it checks if the customer is registered with the company to place an order. If the customer is not registered, then it puts the request message on CUSTOMER.NOT.REGISTERED.Q00 queue and the flow terminates. If the customer is registered, then it assigns a purchase order ID to the request and invokes the CalculatePurchaseOrderPrice sub flow to calculate total price of requested items, discount, shipping charges, applicable taxes, and build pricedPurchaseOrder message. It then stores the priced purchase order in the SAMPLE.PURCHASEORDER database table using warehouse node for audit trail purposes.

The sample application consistently uses the convention to name MQInput and MQOutput Nodes after the queue names served by these nodes to improve the readability of the message flows.

Figure 2: ProcessPurchaseOrder: Main Message Flow. To process the order request further, it has to send a message to the Credit Card Processing system to get approval for the total purchase amount and to the Inventory Control System to check if the inventory for the requested items is in stock. The AggregateCreditAndInventoryControl node marks the beginning of fan-out of requests to the Inventory Control System and Credit Card Processing system. Build the creditApprovalRequest message for the Credit Card Processing System Using the map node, the ProcessPurchaseOrder flow builds the creditApprovalRequest message by extracting credit card information from pricedPurchaseOrder message and setting its physical format to TDS. It sends the creditApprovalRequest message to CREDIT.CHECK.Q00 queue and records the sending of the request in AggregateCreditCheckRequest node which specifies that the response to credit check request should be rooted under the folder CreditApprovalResponse in the aggregated reply message.

CheckCredit message flow simulates the Credit Card Processing System using the DB2 database and processes the credit approval request. Using credit card information from the message, it checks the SAMPLE.CREDITB table to determine if there is a sufficient credit balance to approve the request amount. CheckCredit message flow then builds creditApprovalResponse message in TDS format and sends the response to CREDIT.RESPONSE.Q00 queue. Build msg_StockInquiry message for Inventory Control System Similarly using map node, ProcessPurchaseOrder flow builds msg_StockInquiry message by extracting the parts requested information from pricedPurchaseOrder and setting its format to CWF. It sends the msg_StockInquiry message to the INQUIRE.INVENTORY.REQUEST.Q00 queue and records the sending of the request in the AggregateInventoryRequest node which specifies that the response to the inventory request should be rooted under the folder StockInquiryResponse in the aggregated reply message. CheckInventory2 message flow simulates the Inventory Control System using the DB2 database and processes the stock inquiry request. The stock inquiry and response message have the same message type. In the request message, the ItemQtyAvail field is set to null and in the response message it is either set to 0 or the value of the requested quantity. CheckInventory flow builds output message by copying the input message. For each requested item, it checks the part quantity available in SAMPLE.INVENTORY table and updates the ItemQtyAvail field for the part, as described above, and sends the response message to INQUIRE.INVENTORY.RESPONSE.Q00 queue. The response messages received from the Inventory Control System and Credit Card Processing system are combined into a single aggregated reply message at the AggregateCreditAndInventoryReply node, and this marks the end of an aggregation fan-in. ProcessPurchaseOrder flow then extracts the credit approval response from the aggregated reply and invokes the SendNotification sub flow that sends an email notification to the customer confirming or rejecting his order. Using filter node OrderConfirmed, it checks if the credit approval is okay, and if so, it extracts the inventory response message from the aggregated reply and invokes the UpdateInventory 3sub flow, which updates the inventory and places an order with the supplier if the inventory has gone below a threshold value.

Message processing nodes used in ProcessPurchaseOrder Flow

2

In the next revision of this sample application, we will enhance CheckInventory flow to query the stock items from CICS. For now we are only going to define the interface for the message msg_StockItem that will be used to query the CICS system. This message has been created by importing a COBOL copy and it supports querying of only one part. In the next revision of this sample application, we will enhance UpdateInventory sub flow to update stock items in CICS.

Given below is a brief description of message processing nodes used in the purchase order flow. This section describes some of the relevant parameters that you need to set on these nodes and, wherever necessary, also includes ESQL code snippets associated with some of the nodes to explain the flow logic and/or manipulation of database or message contents.

ORDER.REQUEST.Q00 (MQInput Node)

The MQInput node receives the request from input queue ORDER.REQUEST.Q00. In this node, we set the properties that identify the message domain, message set name, message type and the format in which the message is encoded.

Figure 3. MQInput Node Properties: Identify the message to be processed

Message domains
WebSphere Business Integration Message Broker supports the following message domains: MRM domain: This domain is used for user messages that are modeled or predefined to the Broker. In other words, the broker understands the structural contents of the message and the various physical formats in which the message can be encoded. WebSphere Business Integration Message Broker provides a rich set of tools to create and maintain the modeled messages. Such messages can be created using a spread sheet like Message Editor or they can be created by importing XML Schema, DTD or programming language structures such as COBOL and C. Further information on Message Set and the tools used for creating and building the messages used in this sample, will be covered in Part 2: Message Sets Development using WebSphere Business Integration Message Broker.

Domains used for messages that are not predefined to the broker:
o o XML or XMLNS -- For messages conforming to the W3C XML standard. JMSMap or JMSStream - For messages produced by the WebSphere MQ implementation of the Java Messaging Service standard.

CheckCustomerRegistered (Filter Node)

This node checks if the customer is registered with the company to place the purchase order request by checking the customerID field from the purchase order message against SAMPLE.CUSTOMER database table. If the customer is not registered, the request is rejected and is written to the CUSTOMER.NOT.REGISTERED.Q00 queue. Here we assume that it will be picked

by a front-end application 4 to query the user for registration information and register the customer5. .The following ESQL code checks if the customer is registered with the company. .
CREATE FILTER MODULE ProcessPurchaseOrderFlow_CheckCustomerRegistered CREATE FUNCTION Main() RETURNS BOOLEAN BEGIN DECLARE customerID INTEGER; -- extract the customer ID fro,m the message SET customerID = Root.MRM.customerDetails.customerID; --if the customerID cannot be found in the message then we return unknown IF (customerID is NULL) THEN RETURN UNKNOWN; END IF; -- search the customer table for the customerID SET Environment.Variables = THE (SELECT T.* FROM Database.SAMPLE.CUSTOMER AS T T.CUSTOMERID = customerID); --if the customerID is found return true IF (CARDINALITY(Environment.Variables[])=0) THEN RETURN FALSE; ELSE RETURN TRUE; END IF; END; END MODULE; WHERE

AssignPurchaseOrderID (Compute Node)

If the request is from a registered customer, this node assigns a next available purchaseOrderID from the SAMPLE.PURCHASEORDER database table

CalculatePurchaseOrderPrice (Sub flow)

CalculatePurchaseOrderPrice sub flow calculates the price of the purchase order using the items quantity from the purchase order message and extracting price of the items from SAMPLE.PRICETB database table. It offers a 10% discount if the customer has PREFERRED status and determines the shipping charges which is $10 if number of requested items is > 3 else it is $20. It then calculates tax at the rate of 15% on the total purchase price which includes shipping charges minus the discount. This sub flow uses plenty of ESQL code and shows some of the best practices for writing the ESQL code. Further information on using ESQL and building message flows and sub flows used in the sample will be covered in Part 3: Developing Message Flow Applications using WebSphere Business Integration Message Broker.
4

We are intentionally not describing front end application as there is plenty of material already available on this topic in the developer domain. It will be a typical JSP / Servlet based application running in the WebSphere Application Server.

In the next revision of this sample application, we will build the RegisterNewCustomer message flow. For now, you can update the createSampleData.cmd script supplied with the sample and add entries for customers to be registered

10

StorePurchaseOrder (Warehouse Node)

This node stores the purchase order in the SAMPLE.PURCHASEORDER database table to keep an audit trail of the purchase order. The Warehouse node is a specialized form of the Database node and the interaction is restricted to storing the entire message, or parts of the message, or both, in a table within the database. You define what is to be stored in the database by defining a mapping between the input message and the database table.

Aggregate Node Family

A typical message flow instance at run time has a single thread of execution and once the processing pertaining to a node completes, the control flows to the next node and so on until it reaches the end node, which is typically one of the nodes from the flow completion family such as MQOutput, MQReply, and so forth. Sometimes it is a business requirement (as illustrated in this sample) to send requests to more than one disparate back ends, wait for responses to come back, and then continue the flow execution or decide which path or branch to follow next in the flow depending upon the responses. Also the responses from backend systems may arrive at different intervals and in the worst case, may be due to communication or system failure. Or the responses may never come back, in which case, a time out strategy has to be adopted to either continue or terminate the flow. This is quite a complicated task because it requires multiple threads of execution, synchronization, and timeout consideration, and so on. The WebSphere Business Integration Message Broker Aggregate family of built-in nodes hides all the complexity pertaining to the parallel execution of threads and gives the user the familiar paradigm of wiring these nodes in the flow. Aggregation is an extension of the request/reply application model. It combines the generation and fan-out of related requests derived from a single input message and the fan-in of the corresponding replies to produce a single, aggregated reply message. Fan-out is the process of splitting an input request representing a collection of related request items, into the appropriate number of individual requests to satisfy the subtasks of the input request. Fan-in is the process of combining and merging replies from subtasks (created during the Fan-in process) into a single reply to be returned for the input request. Listed next are the excerpts from the WebSphere Business Integration Message Broker Reference manual on Aggregate family. The aggregation function is provided by the following three nodes: AggregateControl node: Marks the beginning of a fan-out of requests that are part of an aggregation. It sends a control message that is used by the AggregateReply node to match the different requests that have been made. The information propagated from the control terminal includes the broker identifier, the aggregate name property, and the timeout property. AggregateRequest node: Records the fact that the request messages have been sent. It also collects information that helps the AggregateReply node to construct the aggregated reply message. AggregateReply node: Marks the end of an aggregation fan-in. It collects replies and combines them into a single aggregated reply message.

When you include these nodes in your message flows, the multiple fan-out requests are issued in parallel from within a message flow (this is in contrast to the standard operation of the message flow in which each node performs its processing in sequence). This provides an opportunity for

11

an improvement in response time, because slow requests can be performed in parallel and do not have to follow each other sequentially. Since Aggregation is an extension of the request/reply application model, the messages issued by the fan-out message flow, and the responses received by the fan-in message flow, must be request/reply messages.

AggregateCreditAndInventoryControl (AggregateControl Node)

This node marks the beginning of a fan-out of CreditCheck and InventoryRequest that are part of an aggregation CheckCreditAndInventory. This sample aggregates replies in the same flow and hence can connect the control terminals of AggregateCreditAndInventoryControl and AggregateCreditAndInventoryReply nodes directly to pass the control message. This provides a small performance benefit from not having to use a transport such as WebSphere MQ queue to send the control message. The control message carries the broker identifier and user settable properties aggregate name and timeout; in this sample, they are set to CheckCreditAndInventory and 60 seconds respectively.

Figure 4. AggregateControl Node : Specify aggregate name and timeout. However, there are advantages of having a separate message flow to collect replies in which case the control message needs to be transported via queue to control terminal of the AggregateReply node. The advantages are: The two stages, fan-out and fan-in, can be suspended and modified independently of each other. The two stages, fan-out and fan-in, can run in separate execution groups that can make better use of multiprocessor systems.

The design that best suits your business needs depends on your requirements for the application.

ExtractCreditCheckInfo (Extract Node)

12

This node builds the creditApprovalRequest message by extracting credit card related information from the pricedPurchaseOrder message using the mapping facility. It sets the physical format property of the creditApprovalRequest message to TDS_SWIFT as the Credit Card Processing System is expecting to have the message encoded in the TDS format. Mapping is one of the key components of WebSphere Business Integration Message Broker, and it is used pervasively for any task related to extracting or mapping the contents from a source to a target. The source or the target can be a message or a database table. Mapping Editor provides a GUI interface for creating mappings between source and target fields using the familiar drag and drop paradigm. By default, the mapping between the source and target is trivial, where the target takes on the exact value of the corresponding input. In the case where this is not sufficient, you have the facility to associate with a mapping an ESQL function or ESQL expression (which can be created using Compose Expressions editor) to closely define how and when mappings should, or should not, take place. The mappings created with Mapping Editor are stored in a file with an .mfmap extension in the workbench and can be shared among multiple nodes having the similar needs for mapping a source to a target. Mapping can be accessed and maintained through the following nodes: Mapping node DataInsert node DataUpdate node DataDelete node Extract node Warehouse node.

Further information on creating the mappings used in the sample, will be covered in Part 4: Message Transformation using WebSphere Business Integration Message Broker Mappings. Figure 5 shows the mappings created using the mapping editor to build creditCardRequest message from the source message pricedPurchaseOrder.

13

Figure 5: Using Mapping to build Credit Approval Request

CREDIT.CHECK.Q00 (MQOutput Node)

CREDIT.CHECK.Q00 lets you define and generate the characteristics of each output message that is sent to the WebSphere MQ. Figure 6 and 7 show the properties to be set on this node. Select the Request check box to ensure that WebSphere MQ will generate and assign a new identifier for the message. This new message identifier will be remembered by the following AggregateCreditCheckRequest node and will be used as the correlation ID to correlate the response for this request at the AggregateCreditAndInventoryReply node. Also specify the name of reply queue (CREDIT.RESPONSE.Q00) and the reply queue manager (WEBOQMGR) on which the response should be sent back by the message flow which is going to process this request. This node will send the request message to the queue CREDIT.CHECK.Q00 served by the queue manager WEBOQMGR..

14

Figure 6. MQOutput Node: Specify Target Queue manager and Queue name

Figure 7. MQOutput Node: Specify Reply Queue manager and Queue name.

AggregateCreditCheckRequest (AggregateRequest Node)

As mentioned before, this node remembers the message identifier used for the aggregate request that is used as the correlation ID to correlate the response for this request at the AggregateReply node. Here you also specify the folder name (CreditApprovalResponse) under which the response message for the credit check request will be rooted.

15

Figure 8. AggregateRequest Node: Specify folder name under which response will be rooted

ExtractInventoryInfo (Extract Node)

Like ExtractCreditInfo node, this node builds the msg_StockInquiryRequest message by extracting items related to information from the pricedPurchaseOrder message using the mapping facility. It sets the physical format property of the msg_StockInquiryRequest to WINNT as the back end Inventory Control System is expecting to have the message encoded in the CWF format.

INQUIRE.INVENTORY.Q00 (MQOutput Node)

Like CREDIT.CHECK.Q00, the Request check box is selected to ensure that WebSphere MQ will generate and assign a new identifier for the message. This new message identifier will be remembered by the following AggregateInventoryRequest node and will be used as the correlation ID to correlate the response for this request at the AggregateCreditAndInventoryReply node. Here, you also specify the name of reply queue (INQUIRE.INVENTORY.REQUEST.Q00 ) and the reply queue manager (WEBOQMGR) on which the response should be sent back by the message flow that is going to process this request. This node will send the request message to the queue INQUIRE.INVENTORY.REQUEST.Q00 served by queue manager WEBOQMGR.

AggregateInventoryRequest (AggregateRequest Node)

Like the CreditCheckRequest node, this node remembers the message identifier used for the aggregate request that is used as the correlation ID to correlate the response for this request at the AggregateReply node. Here, you also specify the folder name (StockInquiryResponse) under which the response message for the inventory request will be rooted.

16

AggregateCreditAndInventoryReply (AggregateReply Node)

The fan-in flow receives the responses to the request messages sent out by the fan-out flow and constructs a combined response message containing all the responses received. Depending on the timeout values that you have specified, the combined response message is generated. The following diagram shows the aggregated message at the output terminal of this node. The response received from queue CREDIT.RESPONSE.Q00 (response to the credit check request) is rooted under the folder CreditApprovalResponse that was specified in the AggregateCreditCheckRequest node. Similarly, the response received from INQUIRE.INVENTORY.RESPONSE.Q00 (response to Inquire Inventory Request) is rooted under the folder StockInquiryResponse that was specified in the AggregateInventoryRequest.

Reply message is rooted under the folder name specified in the Aggregate Request Node.

Figure 9 Aggregated Reply Message -- Credit Approval and Inventory Inquiry.

17

TIMEOUT.Q00 (MQOutput Node)

If a response from either of the requests is not received within 60 seconds, a time out occurs and the reply message created from the responses received within the timeout period is written to the TIMEOUT.Q00 queue. Any response received after the time out has occurred is ignored.

ExtractCreditCheckResponse (Compute Node)

The aggregated message at the output terminal is not a modeled messaged (that is, it is not predefined in any of the message sets). As a result, we have to use Compute node and ESQL (instead of map node) to extract creditApprovalResponse message (rooted under the CreditApprovalResponse folder) to build an intermediate XML message CreditResponse needed by the SendNotification sub flow. Using customerID from creditApprovalResponse and purchaseOrderID from msg_StockInquiry message (rooted under the StockInquiryResponse folder), extract the customer and purchase order information from the database and append it to CreditResponse message. The following ESQL code is used to build the intermediate CreditResponse message.
. CREATE COMPUTE MODULE ProcessPurchaseOrderFlow_ExtractCreditMessage CREATE FUNCTION Main() RETURNS BOOLEAN BEGIN SET OutputRoot.Properties = InputRoot.ComIbmAggregateReplyBody.CreditApprovalResponse.Properties; SET OutputRoot.MQMD = InputRoot.ComIbmAggregateReplyBody.CreditApprovalResponse.MQMD; -- SET OutputRoot.MRM = InputRoot.ComIbmAggregateReplyBody.CreditApprovalResponse.MRM; -- Extract the PO from the warehouse and append to the message SET OutputRoot.MRM.CreditResponse = InputRoot.ComIbmAggregateReplyBody.CreditApprovalResponse.MRM; -- step 1: extract the purchase order info SET OutputRoot.MRM.PurchaseOrderInfo[] = (SELECT T.* FROM Database.SAMPLE.PURCHASEORDER AS T WHERE T.PURCHASEORDERID = InputRoot.ComIbmAggregateReplyBody.StockInquiryResponse.MRM.purchaseOrderID); --step 2: extract the customer info SET OutputRoot.MRM.CustomerInfo[] = (SELECT T.* FROM Database.SAMPLE.CUSTOMER AS T WHERE T.CUSTOMERID = InputRoot.ComIbmAggregateReplyBody.CreditApprovalResponse.MRM.customerID); RETURN TRUE; END; END MODULE;

SendNotification (Subflow)
Depending upon the credit approval status, this sub flow builds order confirmation or rejection message from the intermediate CreditResponse using the XML transformation node.

18

It writes this message to ORDER.RESPONSE.Q00 queue. If the user had specified the address of the mail server by setting the property SMTP Host Name on the SendEMail node, then it also sends email to the user confirming or rejecting his order. SendEMail node is a custom built node; it uses Java Mail APIs to create and send email messages. This node is built using the Plug-in Node Development feature of WebSphere Business Integration Message Broker. Further details and step-by-step instructions for building this node will be covered in Part 5: Custom Message Flow Node Development using WebSphere Business Integration Message Broker.

OrderConfirmed (Filter Node)

This filter node checks approvalStatus in the creditApprovalResponse to determine if the credit was approved.

ExtractInventoryResponse (Compute Node)

This compute node extracts msg_StockInquiry message rooted under the StockInquiryResponse folder in the aggregated reply message.

UpdateInventory (Subflow)
This sub flow iterates through the Items array in the msg_StockInquiry and calls the back end system to update inventory for each of the requested items. It extracts those items from msg_StockInquiry for which the item quantity has gone below the threshold quantity and thus requires placing an order with the supplier to replenish the items in stock. Using map node, it builds SupplierOrder message for these items. The order quantity in the supplier order is based on three times the reorder quantity for the item plus the current quantity in stock. This sub flow uses advanced features of the mapping and shows how the mapping subroutines can be shared and used in different mappings. Further details on mapping features will be covered in Part 4: Message Transformation using WebSphere Business Integration Message Broker Mappings.

Summary
In this article we have described the integration scenario and how to build an automated Web order processing application sample by loosely integrating the application systems with WebSphere Business Integration Message Broker. We described the concept of message flows and sub flows and provided a high-level description of all the flows used in building this sample. We provided walk through of ProcessPurchaseOrder message flow which process the web order requests and detailed description of the IBM supplied message processing nodes used in building this flow and some of the key parameters that need to be specified on nodes. The rest of the articles in this series will use this sample as the reference and describe in details the tooling features for building message sets, message flows, custom message processing nodes, illustrate advanced mapping capabilities and how to deploy and debug this sample on the broker..

19

Appendix A. Instructions for setting up Web Order Sample

Pre-requisites: WBIMB Service Pack2
Step1
Download WebOrderSample.zip file from the link at below.
Let us assume that the installation location for WBIMB <WBIBBM_Install_Path> is the default: C:\Program Files\IBM\WebSphere Business Integration Message Brokers Unzip WebOrderSample.zip on to folder <Sample_Path>. Lets assume root Sample_Path is the root directory on drive c. This will create the following directory structure in the <Sample_Path> folder: o WebOrderSample WebOrderSampleCustomNode.zip workspace WebOrderProjects You will see following projects in the WebOrderProjects directory WebOrder WebOrderDB WebOrderMessages WebOrderProductInventory WebOrderPurchaseOrder Unzip <Sample_Path>\WebOrderSample\WebOrderSampleCustomNode.zip containing the custom plugin node over the WBIMB installation <WBIBBM_Install_Path> folder. You will see following files: o o SendEmail.jar, TransformMessage.xml, activation.jar, mail.jar at location: <WBIBBM_Install_Path>/jplugin WebOrderPluginNode folder under <WBIBBM_Install_Path>/eclipse/plugins

Start WBIMB studio o Shut down WBIMB studio if it is running. o Start WBIMB studio using web order sample workspace Go to <WBIBBM_Install_Path>/eclipse directory mqsistudio data <Sample_Path>\WebOrderSample\workspace o Use File-> Import -> Existing Project Import wizard to import projects under the folder <Sample_Path>\WebOrderSample\WebOrderProjects into workspace.

20

By the time you are done you should have imported all of the following projects in the workspace: WebOrder WebOrderDB WebOrderMessages WebOrderProductInventory WebOrderPurchaseOrder Use Project->Rebuild All to build the projects

Step2
System Setup o Create user id db2admin with password db2sample . Ensure that the db2admin account is member of all the MQ related workgroups. o Create Queue Manager WEBOQMGR through WebSphere MQ Services Set up Sample Databases o Invoke the DB2 Command Window and change to the following directory <Sample_Path>\WebOrderSample/WebOrderProjects/WebOrderDB/SampleD BSetup o Create Sample Database SAMPLEDB by invoking createDBs.cmd o Create Sample Data by invoking createSampleData.cmd If you encounter any problem while creating database or the sample data and have to start again, you can delete the database while running o deleteDBs.cmd Setup ODBC access for Broker Databases Go to Control Panel->Administrative Tools->Data sources(ODBC) Create System DSN (Data Source Name) for SAMPLEDB using IBM DB2 ODBC Driver (for easy identification keep Database alias name and Data source name identical) Setup Broker Config o o o Invoke the DB2 Command Window and change to the following directory <Sample_Path>\WebOrderSample/WebOrderProjects/WebOrderDB/WebOrderC onfig Create Broker Database ARGODB CONFIGDB using userid db2admin with password db2sample createBrokerDBs.bat Setup ODBC access for Broker Databases Go to Control Panel->Administrative Tools->Data sources(ODBC) Create System DSN (Data Source Name) for ARGODB CONFIGDB using IBM DB2 ODBC Driver (for easy identification keep Database alias name and Data source name identical)

21

Create Configuration manager. User Name Server and broker WEBOBROK. Before Executing the batch file ensure that the correct domain and user account is used within the file. createConfig_webOrder.bat Create Queues used by Integration sample under Queue manager WEBOQMGR webOrderSetup.bat

If you encounter any problem while creating database or broker configuration and have to start again, you can delete the database and configuration by running following o deleteBrokerDBs.bat o deleteConfig_webOrder.bat

Step3
Start WBIMB Processes o Stop the default queue manager which is created when you install the MQSeries. The default queue manager name is typically QM_<hostName> o Ensure WEBOQMGR is running and Listener is listening on port 1414. o Go to Control Panel->Administrative Tools->Services and start the following start ConfigMgr start UserNameServer start WEBOBROK o Go to Control Panel->Administrative Tools->EventViewer - check there are no errors in starting these processes

Step4 (optional)
Update properties on SendEMail node to get Order confirmation via eMail o Open SendConfirmation.msgflow and set following properties on the SendEMail node SMTP Host Name: specify the tcp address of the mail server. Default Sender Address: senders email address Default Sender Name: Senders Name Modify the email address for the customers in the createSampleData.cmd to the appropriate email address. A snippet from this command file shown below for reference o DB2 INSERT INTO SAMPLE.CUSTOMER ( CustomerID,Prefix,FirstName,LastName,CustomerName,OfficeP honeNo,emailAddress,BillStreetNo,BillCity,BillState,BillP ostCode,BillCountry,RegnDate, CustomerType) VALUES ( 004, 'Mr.', 'Adam', 'Smith', 'Acme Corporation', '(888) 8888888', 'TestSample@hotmail.com', '555 Richmond Street', 'Toronto', 'ON', 'L6G 1C7', 'Canada', '2002-1120', 'PREFERRED') Drop sample database SAMPLEDB, recreate this database and the sample data as described in Step2

22

Step5
Deploying Web Order Sample to Broker o o Go to Broker Administration Perspective o Create domain File->New->Domain Choose WEBOQMGR for queue manager and connection_WebOrderServer for the connection name as following screen show

Create broker File->New->Broker Choose WEBOBROK for broker and WEBOQMGR for the queue manager and click on Complete Deploy when prompted

23

Create broker archive file WebOrder.bar o Select File->New->Message Broker Archive o Create broker archive file name WebOrder.bar o Select all the following projects and add them to the archive: WebOrder WebOrderMessages WebOrderProductInventory WebOrderPurchaseOrder

Drag and Drop WebOrder.bar on the default execution group under WEBBROK

24

If deployment is successful you will see following message flows and message sets in the Domain pane

Step6
Running the Web Order Sample The current flows in the sample assume that you are a registered customer and have been assigned a customer ID. createSampleData.cmd in Step2 had registered a couple of customers in CUSTOMER table in SAMPLEDB. We have supplied a set of purchase order messages as if these were requests from these customers in the WebOrderPurchaeOrder project under the folder sourceMessages\purchaseOrders Switch to Broker Administration perspective Use File->New->Enqueue Message file wizard to create SampleTestMessage.enqueue file in the WebOrderServer project.

25

When you press finish, the enqueue message file editor will open. o Using browse button , select WebOrderPurchaseOrder project. Select file sourceMessages\purchaseOrders\PurchaseOrder_AdamSmith.xml

Use WEBOQMGR for queue manager name and ORDER.REQUEST.Q00 for the queue name

26

o o

Press writeToQueue to send a message to ORDER.REQUEST.Q00. If everything works you will get a Purchase Order Confirmation notification in ORDER.RESPONSE.Q00 queue. You can read the message from the queue using toolbar button Dequeue Message. Given below is the sample message read from the queue
<root> <to>TestSample@hotmail.com</to> <subject>Your purchase order has been approved!</subject> <body><html><body> <b>Dear Mr. Adam Smith ,</b><br><br> Your purchase order has been received and approved!&nbsp;&nbsp;<img src="http://messenger.msn.ca/Resource/emoticons/thumbs_up.gif"><br> Please verify that the order details and your mailing information are correct.<br> <table> <tr><td colspan="4"><br><b>Order Details:</b></td></tr> <tr><td width="20"/><td align="right"><i>Total:</i></td><td width="10"/><td>$ 52.90 </td></tr> <tr><td colspan="4"><br><b>Mailing Information:</b></td></tr> <tr><td width="20"/><td align="right"><i>Name:</i></td><td width="10"/><td> Adam Smith </td></tr> <tr><td width="20"/><td align="right"><i>Phone:</i></td><td width="10"/><td> (888) 8888888 </td></tr> <tr><td width="20"/><td align="right"><i>Email:</i></td><td width="10"/><td> TestSample@hotmail.com </td></tr> <tr><td width="20"/><td align="right" valign="top"><i>Address:</i></td><td width="10"/><td width="500"> Acme Corporation<br> 555 Richmond Street<br> Toronto, ON<br> L6G 1C7, Canada </td></tr> </table> </body></html></body> </root>

27

If you had set the properties SMTP Host name , Default Sender Address and name in the SendMail node in SendConfirmation.msgflow , you will get email notification to the email address specified for the customer in the CUSTOMER table in SAMPLEDB. Here is the sample formatted email message :

References
o http://www-306.ibm.com/software/integration/wbimessagebroker/

About the author

Suman Kalia is an Advisory Software Developer at IBM Toronto Laboratory in Toronto Ontario,
Canada. He is the team lead for Message Set Development tools for WebSphere Business Integration Message Broker. You can reach Suman at kalia@ca.ibm.com

Evan Mamas is a Staff Software Developer at IBM Toronto Laboratory in Toronto Ontario, Canada. Evan is currently on study leave and is pursuing masters program at MIT, USA. You can reach Evan at emamas@mit.edu Dave Spriet is a Staff Software Developer at IBM Toronto Laboratory in Toronto Ontario,
Canada. He is working on the Message Set Development Tools for WebSphere Business Integration Message Broker. You can reach Dave at spriet@ca.ibm.com

28

Trademarks DB2, IBM, and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml

29