Sample Use Case and Code
Recall that in the series of examples shown in the previous three chapters, a message was sent asynchronously using clients in both .NET and Java. To expand on this and to highlight the functionality that BizTalk Server 2004 can provide, we'll continue using this asynchronous approach but will create a BizTalk Server orchestration based on a use case.
The use case shown in this section is based on the stock-trading examples used in previous chapters. The samples in this chapter will show how an order message submitted by a client can be processed by a BizTalk Server orchestration. The orchestration will execute decision logic to determine which external Web services to call to fulfill the order. A result message will be created at the conclusion of the business process and will be returned to the client. This overall flow can be seen in Figure 11.8.
Figure 11.8: The sample stock processes orchestration running on BizTalk Server 2004.
To start, the order will be submitted from the client to BizTalk Server 2004 and will use the schema shown in Table 11.1.
| Field | Type | Description |
|---|---|---|
| Ticker | String | Used to identify the stock |
| Qty | Integer | Used to identify the quantity of shares |
| Action | String | Used to identify the action required (BUY or SELL) |
| | String | Used to identify the user |
As an example of this schema in action, the following could be a valid order to purchase 1000 shares of the stock represented by the ticker WOOD:
<ns0:Order xmlns:ns0="http://StockProcesses.Order"> <Ticker>WOOD</Ticker> <Qty>1000</Qty> <Action>BUY</Action> <Email>samples@microsoft.com</Email> </ns0:Order>
As you can see, the order consists of a ticker symbol, a quantity, an action (BUY or SELL), and an e-mail address to identify the sender. Upon receiving the incoming message, the instance of BizTalk Server will start an orchestration. As mentioned earlier, an orchestration is a business process that coordinates message processing among various internal entities (such as a C# component) and external entities (such as a Web service).
The first step in the orchestration is the receipt of the order message. Next , the price for the stock is resolved by using a Web service that will return the current price based on the ticker symbol. After the price is returned, the total value of the order is calculated (by multiplying the stock price by the quantity requested ). If the total value of the order is more than $250, the user will qualify for a smaller commission for this trade: $5.95. If the value is less than $250, the commission remains at the regular price of $19.95.
After the order commission is determined, the ticker symbol will be used to resolve a name for the company. This resolution will again be performed by calling a second Web service, passing it the ticker symbol, and returning a String . For example, if the ticker symbol WOOD is passed, the Web service will return a String containing Woodgrove Bank as the full name.
This resolved name, together with the current price and other details in the incoming order, will be used to construct a purchase or sale request that uses a schema, highlighted in Table 11.2. This request is the same as those shown in Chapter 5, "Connectivity with XML Web Services, Part 1," and Chapter 6, "Connectivity with XML Web Services, Part 2."
| Field | Type | Description |
|---|---|---|
| Ticker | String | Used to identify the stock |
| Name | String | Used to identify the stock |
| Price | Double | Offer price for the stock |
| Previous | Double | Used for output only |
| Volume | Integer | Used to specify quantity for incoming requests . |
The action field within the incoming order will determine whether this request is sent to a Java Web service (to indicate that the user wants to sell stocks) or to the .NET Web service (to indicate a purchase). After the sale or purchase has been made, a confirmation message will be created and returned to the client. The schema for this final message is shown in Table 11.3.
| Field | Type | Description |
|---|---|---|
| Ticker | String | Used to identify the stock |
| Message | String | Message to the user |
| Price | Double | Offer price for the stock |
| Qty | Integer | Number of shares |
| Name | String | Used to identify the stock |
| Commission | Double | Commission charged for this trade |
This is an example of such a confirmation:
<ns0:Fulfillment xmlns:ns0="http://StockProcesses.UserResponse"> <Ticker>WOOD</Ticker> <Message>Your order was fulfilled. An email has been sent to samples@microsoft.com</Message> <Price>14.45</Price> <Qty>1000</Qty> <Name>Woodgrove Bank</Name> <Commission>5.95</Commission> </ns0:Fulfillment>
This typical confirmation message includes items from the original order, returned results from the Web services, and the calculated commission value. Once the confirmation is delivered to the client, the orchestration is considered complete.
Building the Web Services
To start building this Web service by using BizTalk Server 2004, you must first decide on a location and platform for the Web services. To demonstrate that BizTalk Server can call Web services written in both .NET and Java, we'll split the services between the two.
The Web services that provide stock quotes and allow the user to purchase stocks will be hosted by .NET, while the Web services that provide name resolution (finding out a company name from a stock ticker) and allow the user to sell stocks will be written in Java. Before we see the orchestration, we need to build and deploy these Web services. All of these Web services can be found in the C:\Interoperability\Samples\Resource\BizTalk\WebServices directory.
To build the .NET Web services, navigate to the dotNET subdirectory. Within this directory are the two subdirectories, BuyService and PriceService, which contain the required code for the two .NET Web services. For each of these services, use the provided NAnt script in each subdirectory to compile the code. Once compiled, launch the Microsoft Internet Information Services (IIS) administration tool by selecting the program from the Start/Programs/Administrative Tools menu. In the tool, expand the Web Sites folder and right-click Default Web Site. Select New/Virtual Directory to bring up the Virtual Directory Creation Wizard.
Enter the alias for the buy stocks Web service. For this sample, the alias must be dotNETBuyWebService , as shown in Figure 11.9.
Figure 11.9: Creating the new virtual directory for the buy stocks Web service.
In the next part of the wizard, set the location of the virtual directory to C:\Interoperability\Samples\Resource\BizTalk\WebServices\dotNET\BuyService , as shown in Figure 11.10. Accept the defaults for the rest of the wizard to create this Web service.
Figure 11.10: Specifying the location of the Web service files.
Repeat the process for the pricing Web service. For the sample to work correctly, the alias for the pricing Web service must be entered as dotNETPriceService , as shown in Figure 11.11.
Figure 11.11: Creating the virtual directory for the .NET pricing Web service.
For the location of the pricing service, ensure that C:\Interoperability\Samples\Resource\BizTalk\WebServices\dotNET\PriceService is used. Complete this wizard by accepting the default values, which concludes the setup of the two virtual directories required for the samples.
For the Java Web services, navigate to the C:\Interoperability\Samples\Resource\BizTalk\WebServices\Java directory. The two Web services (for the naming and selling of stocks) are located in this directory. To build and deploy these two Web services, execute the Ant script by using the run target within this directory. Entering start ant run at a command prompt within this directory will compile and publish the Web services by using a separate command prompt window. This will publish the Web services at http://localhost:8004/JavaWebService/NamingService.wsdl and http://localhost:8004/JavaWebService/StockService.wsdl , respectively.
If you followed the samples shown in Chapters 5 and 6, you might be wondering why the Web services used to buy and sell stocks are being redeployed. In this case, these Web services contain only the methods required for buying and selling the stocks ”they don't contain the methods for retrieving recommendations.
Once both the .NET and Java Web services have been compiled and published, it's a good idea to validate that they have been deployed correctly. Navigating to the Web Services Description Language (WSDL) file for each of the Web services will confirm this.
The Stock Processes Orchestration: Step by Step
Now that the Web services are deployed, we can take a look at the BizTalk Server solution. Instead of creating the orchestration and related artifacts from scratch during this chapter, you can find the completed BizTalk Server 2004 solution in the C:\Interoperability\Samples\Resource\BizTalk\Project directory. The main solution file for the sample (StockProcesses.sln) should be opened with Microsoft Visual Studio .NET 2003. Note that it isn't possible to view the BizTalk Server orchestration or compile the project without first loading the solution into this integrated development environment (IDE).
Open the solution file, and display the ProcessOrder.odx file. This will show a graphical representation of the BizTalk Server orchestration, as displayed in Figure 11.12.
Figure 11.12: The orchestration designer, as shown in Visual Studio .NET 2003.
Let's now step through this orchestration to observe the tasks that will be executed. At the top left, the orchestration is activated based upon an incoming order. Notice how the OrderFromUser message is received at a "port" named IncomingOrder in a part of the orchestration design pane. This section of the design pane is known as the Port Surface and is shown in Figure 11.13. The Port Surface shows all the entry and exit points (ports) for messages flowing to and from the orchestration. Ports can define one-way or two-way (request- response) message flows.
Figure 11.13: The incoming order port within the orchestration.
We'll define endpoint information for this port as we deploy the orchestration, but for now imagine this port as a logical input point to the orchestration itself. As you can see here, the port delivers the incoming order message to a Receive shape in the orchestration.
How do we define the type for the incoming order? In BizTalk Server 2004, a message's type is defined either by an XML Schema Definition (XSD) document or a .NET class. We use XSD to define a message type here, similar to the way we used XSDs to define data types in Chapters 5 and 6. The XSD document for the incoming order is defined in the Order.xsd file. If you open this file within the BizTalk Server solution, the XSD is displayed in the BizTalk Server Schema Editor. Order.xsd defines Ticker , Qty , Action , and Email elements, similar to the schema shown earlier in the use case section.
This is the type of message that the client will be sending to the deployed orchestration. Let's return to the orchestration. Once the incoming order is received, a new message is created and a call is made to our first Web service.
The Construct Message shape shown in Figure 11.14 is used to create a new message that you'll send to the service that will return the current stock price. The Assign stock ticker message assignment contains the following code and is used to set the parameter of the request to the value of the ticker in the incoming order:
RequestForStockPrice.ticker = OrderFromUser.Ticker;
Figure 11.14: The outgoing port to the .NET pricing Web service.
After the message is constructed , a send/receive mechanism is used to call the.NET Web service. Notice how this Web service is represented as a second port in the orchestration.
The Web service port ( PriceServicePort ) was added to the BizTalk Server Port Surface simply by completing an Add Web Reference within the Visual Studio .NET 2003 BizTalk Server project. By simply pointing to the WSDL for the Web service, the BizTalk Server artifacts required to communicate with that service are automatically added to the project. Expanding the Web References folder in the Solution Explorer shows a list of Web services that have been added to the project this way, as shown in Figure 11.15.
Figure 11.15: The list of Web references used by the BizTalk Server project.
As with the other examples used throughout the book, we could have also used the WSDL tool to define these Web proxy files. However, adding the reference to the Web service by using the IDE provides a natural way for BizTalk Server 2004 to create a port.
After the price has been returned for the stock, the next stage in our use case is to determine whether the total value of the order is greater than $250. If the order is less than this amount, the commission will be $19.95; if the order is more, the commission will be $5.95.
To facilitate this type of decision, BizTalk Server 2004 uses a Decision shape, which is used to conditionally branch based on a logical expression. Any number of conditional branches can be specified, but in this case, we effectively have an if branch and an else branch. This is shown in Figure 11.16.
Figure 11.16: The Decision shape, used to branch based on the value of the order.
As shown, if the order is less than $250, a high commission rate message is constructed. If the order is greater than $250, a lower price is used instead. The conditional logic to determine whether the order value is above or below this limit can be found within the Decision shape. Double-clicking the Yes box will show the expression used to make this decision:
(ReturnedStockPrice.getPriceResult * OrderFromUser(Qty)) < 250
The expression shows how the result from the .NET pricing Web service is multiplied by the quantity supplied in the incoming order from the user. If this value is true , the orchestration continues through the high commission route ” if not, the else branch is used instead. The value of the commission itself is stored in a BizTalk Server message named Commission , which is defined as a data type of System.Double .
You now have the price and commission for the trade. The next step in the orchestration is to resolve the name of the stock. This name is used to construct the purchase or sale request and is calculated in a way very similar to the way the price was calculated. This is shown in Figure 11.17.
Figure 11.17: The call to the Java-based naming Web service.
Again, a message that defines the request for the name is constructed. The assignment takes the stock ticker from the order and uses that as the parameter to call the Web service. The Web service (shown as NamingServicePort ) is based on a Web Reference that has been added to the BizTalk Server project and happens to be the first Java Web service to be called.
Once the name has been returned from this Web service, another Decision shape is used to determine whether the order is a purchase or sale. This will ultimately decide whether the .NET BuyStocks or Java SellStocks Web service is called to actually process the request.
As Figure 11.18 shows, the Decision shape determines whether the order is considered a purchase or sale. (The OrderFromUser.Action is tested to validate this.) Based on this decision, the orchestration follows one of two similar branches to process the request.
Figure 11.18: The Decision shape used to determine whether the process is a purchase or sale.
First, either a purchase or sale message is constructed. This is a two-part construction that first uses a transform and then a message assignment to set values of the request. A transform (often referred to as a map ) within BizTalk Server 2004 is an artifact that describes how to map elements of one message type to the elements of a second message type. In this sample, two maps are required because the incoming order needs to be transformed at run time to either the purchase or the sale message. To see more closely how a transform works, open the TransformToBuyStock.btm file in the Solution Explorer.
This simple transformation, displayed in Figure 11.19, shows how the Ticker and Qty elements in the incoming order message are mapped directly to the Ticker and Volume elements, respectively, in the outgoing purchase message.
Figure 11.19: A transform showing the mapping between an order and outgoing request.
The BizTalk Mapper includes a rich and extensible palette of functoids that facilitate reusable and complex transformation logic. Prebuilt functoids support string manipulation, mathematical and logical functions, and data conversion. For example, a functoid could be used to adjust the Qty element by a fixed amount, or to pad the Ticker string field with 10 spaces.
Returning to the orchestration, the assignment to either the purchase or the sale message effectively sets the Name and Price for the request:
RequestToBuyStock.stockToBuy.Name = ReturnedStockName.getNameResult; RequestToBuyStock.stockToBuy.Price =(System.Single)ReturnedStockPrice.getPriceResult;
Recall how these fields are set based on the results from the .NET pricing and Java naming Web services.
After either the BuyStocks or SellStocks Web service is called, the confirmation message is finally constructed for the user. This is a message that indicates the original ticker value and quantity, the name and price of the stock (as resolved by the Web services), and the commission charged. The Email address is also used in the message to simulate a confirmation being sent.
You use a third transform and assignment, shown in Figure 11.20, to take the original incoming order and construct the confirmation. This confirmation is then sent to the outgoing port and will be based on the schema that was outlined in the use case.
Figure 11.20: The final, late-bound outgoing port.
Within this orchestration, you've seen how the calls to the .NET and Java Web services are represented by ports that were defined by Web References added to the BizTalk Server project. You've also seen that the initial incoming and final outgoing operations are ports, but these are known as logical , or late- bound , ports. Endpoint information for these logical ports is defined outside the orchestration itself. This allows a compiled orchestration to be reused in a variety of deployment environments without having to be recompiled.
Let's now take a look at the steps required to define endpoint information for these logical ports and ultimately deploy this orchestration to the BizTalk Server.
Deploying the Orchestration
To compile the BizTalk Server 2004 project, select Build Solution from the Build menu. After building, you need to deploy the solution. There are two ways you can do this. Deployment can be performed by manually stepping through and creating the ports, or you can use a deployment script. Running the deployment manually will give you an insight into how late-bound ports are created in BizTalk Server 2004, but using the script will allow you to get the sample running in less time. Both of these methods are covered in this section.
For both the deployments, we'll use one-way FILE ports that send and receive XML message instances to and from well-defined folders in the file system. This gives us an easy, platform-neutral way of testing the orchestration with a number of permutations .
As mentioned previously, because these ports are late-bound, you're free to replace the FILE ports with any of the available port types. This might include combining the two separate one-way FILE ports into a single request- response Web service port. Alternatively, you could connect the orchestration to a running instance of either MSMQ or WebSphere MQ. We'll discuss some of these port options in the section on extending this sample.
Deploying Manually
To begin a manual deployment, select Deploy Solution from the Build menu. This will deploy the compiled orchestration to the local running instance of BizTalk Server 2004.
After the deployment has completed and while you're still within Visual Studio .NET, click the View menu and select BizTalk Explorer. This is a tool that shows the deployed assemblies, orchestrations, and ports. Expand the assemblies and orchestrations, as shown in Figure 11.21, to check that the project was deployed successfully.
Figure 11.21: Viewing the BizTalk Explorer within Visual Studio .NET.
Before you start the orchestration, you must first create actual endpoint information for the late-bound incoming and outgoing ports. Recall that the incoming port is used to accept incoming orders and the outgoing port is used to return the confirmation.
Creating the late-bound incoming port
To create the incoming port, right- click the Receive Ports folder within the BizTalk Explorer. Select the Add Receive Port option to create a new Receive Port.
For the type of port, select One-Way Port, as shown in Figure 11.22. Because we'll next define a file system location to represent the endpoint from which we receive incoming orders, this must be a one-way message flow. Click OK to confirm the type of Receive Port. In the property sheet that's displayed, change the name of the port to IncomingOrderPort , as shown in Figure 11.23.
Figure 11.22: Adding a new incoming port.
Figure 11.23: Configuring the details for the incoming port.
Click OK to create the port. You now need to create a location at which the port receives messages. This will specify the location and file types for the incoming orders. To do this, right-click the Receive Locations folder that appears under the newly defined port in BizTalk Explorer, and select Add Receive Location.
The Transport Type should be set to FILE . For the Address (URI), click the ellipsis button () that appears in this field. This will display a second dialog box that allows you to accurately specify the folder, as shown in Figure 11.24.
For the Receive Folder, enter the location of the in-files folder. The in-files folder is a subfolder of the BizTalk Server project itself and should be C:\Interoperability\Samples\Resource\BizTalk\Project\in-files . If you have installed the samples to a different location, you'll need to alter this folder to reflect your own settings.
For the file mask, enter *.xml and click OK to close this dialog box. This tells BizTalk Server that only files ending in .xml in this folder location should be picked up and delivered to the Receive Port defined previously.
Back on the property sheet, the Receive Handler should be set to BizTalkServerApplication and the Receive Pipeline should be set to XMLReceive . Once these settings are confirmed, as shown in Figure 11.25, click OK to save the Receive Location.
Figure 11.24: Setting the folder properties for the FILE transport.
Figure 11.25: Configuring the details for the new Receive Location.
Creating the late-bound outgoing port
You now need to create the outgoing port. This port will be very similar to the incoming one. But instead of receiving XML files in the in-files folder, this port will create XML files in the out-files folder of the project.
Within the BizTalk Explorer and the Visual Studio .NET IDE, right-click the Send Ports folder and select the Add Send Port option, as shown in Figure 11. 26. As with the incoming port, this will be a (static) one-way type.
Figure 11.26: Creating a new send port.
Again, rename the port to something a little more meaningful ”for this example, use OutgoingPort . Set the transport type to FILE , and again for the address, click the ellipsis button in the field.
In the dialog box that appears (see Figure 11.27), enter the destination folder to be the out-files folder of the sample project ( C:\Interoperability\Samples\Resource\BizTalk\Project\out-files ). Again, modify this path if the sample code hasn't been installed to the C:\Interoperability folder.
Figure 11.27: Configuring the destination for the FILE transport.
Ensure that the filename is set to %MessageID%.xml . This tells BizTalk Server to use a unique message identifier as the name of the output file saved onto the file system. This way, the orchestration can run more than once without overwriting the result message in the output folder. When you're done, click OK to close the File Transport Properties window.
Now expand the Send\General option in the properties window and set the Send Pipeline to XMLTransmit , as shown in Figure 11.28.
Figure 11.28: Completing the configuration of the outgoing port.
The properties for the outgoing port will now be properly configured, as shown in Figure 11.29.
Figure 11.29: Setting the properties for the outgoing port.
Click OK. This will create the outgoing port. You're now ready to start and test the orchestration.
Deploying with a Script
In addition to the manual steps just described, deployment can be performed automatically with a script. The script is loaded and run by the BizTalk Deployment Wizard, which can be launched by selecting it from the Start\Program Files\BizTalk Server 2004 program group . If you've already followed the manual deployment, you can skip this section.
After the wizard has been launched, select the option Deploy BizTalk Assembly To Database, as shown in Figure 11.30. This option allows you to select the compiled BizTalk Server assembly and reference a binding file that will preconfigure the ports.
Figure 11.30: Launching the BizTalk Deployment Wizard and selecting an action.
In the next screen of the deployment wizard, select the machine that contains the BizTalk Server database, as shown in Figure 11.31. Ensure that the database points to the BizTalk Server Management Database, the default name for which is BizTalkMgmtDb. For these samples, I'll use the same machine.
Figure 11.31: Selecting the BizTalk Server database to perform the deployment.
In the next screen in the wizard, you need to select the compiled BizTalk Server assembly (DLL file) and the script, as shown in Figure 11.32.
Figure 11.32: Specifying the location of the BizTalk Server assembly and bindings file.
For the DLL file, enter the following location:
C:\Interoperability\Samples\Resource\BizTalk\Project\bin\Development\StockProcesses.dll
For the binding file, use
C:\Interoperability\Samples\Resource\BizTalk\Deployment\binding.xml
This is the predefined deployment script for the sample code. Also ensure that the option to install the assembly into the global assembly cache (GAC) is selected. If you have installed the sample code to a directory other than C:\Interoperability, you should edit the binding.xml file and replace all occurrences of this with your installation path.
Once these values have been entered, finish the wizard to complete the deployment of the sample orchestration.
Starting the Orchestration
The final piece of the BizTalk Server project sample is to start the orchestration running. To start, if not already displayed within Visual Studio .NET, click the View menu and select BizTalk Explorer. Right-click the StockProcesses.StockProcesses.ProcessOrder orchestration in BizTalk Explorer (found in the Orchestrations folder), and select the Bind option. This is used to bind the orchestration to the ports that we've just created either manually or with the script. If you don't see this assembly, right-click the machine name in BizTalk Server Explorer and select Refresh.
In the Binding option, ensure that the IncomingOrder and OutgoingPort fields are set to the incoming and outgoing ports that were just created, as shown in Figure 11.33. Note that the Web service port binding is already established because the endpoint information was automatically created when the Web service references were added to the BizTalk Server project.
Figure 11.33: Checking the binding properties for the orchestration.
In the Host option, ensure that the host is set to BizTalkServerApplication , as shown in Figure 11.34.
Figure 11.34: Checking the host properties for the orchestration.
Once configured, click the OK button. Now that the orchestration is fully bound to the ports, you start the orchestration and begin sending it messages. Right-click the StockProcess orchestration again, and select Start.
In the dialog box that appears (see Figure 11.35), select all the dependency options and click OK. This process will take a few seconds to start.
Figure 11.35: Selecting dependencies and starting the orchestration.
If the orchestration is running correctly, the color of the orchestration icon displayed in BizTalk Explorer should change and become more prominent. This means that the orchestration is ready to process messages.
Testing the Orchestration
To test the orchestration, we'll use some precreated sample order XML files. These files can be found in the C:\Interoperability\Samples\Resource\BizTalk\Project\test-files directory. This directory contains four files:
purchase-high-commission.xml purchase-low-commission.xml sale-high-commission.xml sale-low-commission.xml
Each of the files is used to test various aspects of the orchestration. For example, purchase-low-commission.xml will be used to submit a purchase that should result in a low commission fee for the user. Likewise, sale-high-commission.xml shows a sale that will result in a high commission for the user.
Open the purchase-low-commission.xml file to examine the structure:
<ns0:Order xmlns:ns0="http://StockProcesses.Order"> <Ticker>WOOD</Ticker> <Qty>1000</Qty> <Action>BUY</Action> <Email>samples@microsoft.com</Email> </ns0:Order>
This is a relatively simple file that describes the incoming order for the BizTalk Server process. As covered earlier in the use case discussion, the order has a ticker (WOOD), a quantity of shares (1000), an action (BUY), and an e-mail address. If the orchestration works correctly, you should observe that this order triggers the .NET Web service to purchase a stock and has sufficient quantity to take the order of more than $250 (and result in a low commission).
Make sure that the Java naming and stock Web services are running in a command prompt window. To run the orchestration, from within Windows Explorer copy the purchase-low-commission.xml file from the test-files folder to the in-files folder. Do ensure that the file is copied and not moved (because BizTalk Server will eventually delete the incoming file once it's delivered to the orchestration).
If the orchestration can pick up this message, the file will disappear within a few seconds of being copied to this folder. If the file doesn't get picked up, check to see that the orchestration is running and check the Event Log to see whether there are any relevant warnings or errors.
Before we look at any output that was produced, let's validate that the Web services were called. Open the Event Log and check the Application Event Log. In here, with a date/time of when the orchestration was run, you should see a message that indicates that the pricing Web service was invoked by the orchestration and returned a value.
This confirms that the pricing Web service was correctly called. Next, you can check the Java Web service that performs the name lookup for the company. In the console window that's running the Java Web service, you should see a request for the name of the company that matches the Ticker, WOOD.
The Java Web service will return the name Woodgrove Bank for this ticker. Now switch to the Event Log. If the .NET BuyStocks Web service was able to successfully accept the request, a second entry should be logged in the Application Event Log.
As you should observe in the Event Log, the incoming .NET Web service successfully accepted the request to purchase stock from the BizTalk Server orchestration. Although this Web service writes to the Event Log, you can imagine how a real trade could be invoked in a production system.
Finally, let's view the output that was generated from the orchestration itself. Navigate to the C:\Interoperability\Samples\Resource\BizTalk\Project\out-files directory. This directory should contain an XML file that has a date/time that matches when the orchestration completed. The name of the file will be a unique ID. Open this file in Microsoft Internet Explorer or another XML editor.
You should see confirmation of the order itself, similar to the output shown in Figure 11.36.
Figure 11.36: The final confirmation of the order generated by the orchestration.
In the XML file depicted, you can see that the order confirmation contains the ticker and a message to indicate that an e-mail was sent. (An e-mail message wasn't actually sent, but you can create a BizTalk Server Send Port that uses Simple Mail Transfer Protocol, or SMTP, to achieve this.) The price and name returned from the Web services are also displayed, as well as the commission that was calculated based on the value of the order ($14.45 x 1000 is indeed over $250).
Retest the orchestration by using the other XML orders in the test-files directory. For the Java Web services that are called by the orchestration, the output will be written the console window. For the .NET Web services, all output is written to the Application Event Log.
Extending the Sample
As you've seen, the sample used one-way FILE Receive and Send Ports to accept incoming orders represented as XML document instances, and to produce some output as well as an XML document. Although this works well with the sample code, chances are that in a production environment, ports that use other transport mechanisms will need to be employed. At the time of this writing, BizTalk Server 2004 is still in beta, meaning that many "adapters" that address this need are still in development. However, if you look at BizTalk Server 2002, you can see that there are more than 350 adapters (known in BizTalk Server 2002 as Application Integration Components, or AICs) available for selection. One of the AICs available today for BizTalk Server 2002 is used to connect to WebSphere MQ/MQSeries.
WebSphere MQ/MQSeries Support
Chapter 9, "Asynchronous Interoperability, Part 2: WebSphere MQ," and Chapter 10, "Asynchronous Interoperability, Part 3: Bridging with Host Integration Server," looked at how WebSphere MQ could be used to provide interoperability between clients and services in the .NET and Java programming environments. In these chapters, you saw how to use direct methods and the MSMQ- MQSeries bridge to achieve this.
With BizTalk Server 2002, you can use the MQSeries AIC to provide connectivity with WebSphere MQ (MQSeries). An equivalent adapter is planned for BizTalk Server 2004. The Microsoft BizTalk Adapter for MQSeries provides a port that will enable connection to an existing instance of WebSphere MQ.
If you were to expand on this example, you could see how instead of sending and receiving XML files to and from the file system, the MQSeries adapter could be used to receive the incoming order message from and place the outgoing confirmation message onto WebSphere MQ queues. This would then allow any external clients connected to these queues to send messages to or receive them from the BizTalk Server orchestration.
Inbound Web Services Support
Another interesting modification of the sample would be to expose the orchestration itself as a Web service. BizTalk Server provides a step-by-step wizard for publishing a compiled orchestration as a Web service. Note that this requires replacing the incoming and outgoing FILE ports with a single two-way SOAP port. Combined with the full suite of adapters, this offers a flexible and powerful way to connect the orchestration to external systems.
Exception Handling
One orchestration feature that wasn't shown in the sample was the handling of exceptions. You can effectively add a catch exception block to any set of orchestration shapes that are grouped into a scope. Scopes themselves can be nested. Within a Web services environment, where multiple Web services could potentially be called, such exception handling is an important consideration.
In the sample as written, if one Web service fails, the orchestration fails and the message is suspended . A more suitable approach would be to use the exception handling supported directly within the orchestration to provide some kind of corrective action if an error occurs. In a production environment, this could involve defaulting to a backup Web service, or if a more fatal exception occurs, having the ability to notify the user via e-mail to indicate that the order was unsuccessful . A more complex design could notify an external party of the problem and pause the orchestration until a notification to continue is supplied by that external party.
Enabling Transactions
Again, because this was a simple example designed to show orchestration of both .NET and Java Web services, it didn't cover transactions. Transaction support is a key feature of BizTalk Server orchestration. An atomic transaction in BizTalk Server is typically short-lived and is used to identify a portion of an orchestration that must exhibit these attributes: Atomicity, Consistency, Isolation, and Durability (ACID). Operations within an atomic transaction are guaranteed to complete successfully or are all rolled back in the event of an error during the lifetime of the transaction.
| More Info | See Chapter 8, "Asynchronous Interoperability, Part 1: Introduction and MSMQ," for additional details on operations within an atomic transaction and for an example. |
BizTalk Server also supports long-running transactions for cases in which traditional ACID transactions aren't possible or aren't desired. A long-running business process that might take many days or weeks to complete clearly can contain pieces that are atomic, but the process as a whole isn't normally expected or required to be ACID. Long-running transactions offer consistency and durability but are neither atomic nor isolated.
The real importance of long-running transactions is found in the concept of compensation. Every atomic and long-running transaction can be optionally associated with a compensation block . The purpose of a compensation block is to specify behavior that reverses (compensates for) the effects of an already- committed transaction. For example, the first part of a long-running business process might require inserting a new record into a database, sending an e-mail notification of this event, and committing these two operations as an atomic transaction. Three hours later an error might occur in the execution of a later part of the long-running business process. Unless such an error can be handled gracefully, the business process might need to compensate for the already-committed transaction. In this simple example, the compensation block for the atomic transaction can perhaps delete the previously inserted database record and send a second e-mail message notifying someone of this event.
Within the orchestration designer, a number of shapes can be grouped to identify such a transaction boundary that spans one or more processes. Obviously, if messages are being sent externally, the external port must offer some transactional support. For message queues, this can be achieved today. For Web services, I'm confident that in the near future, we'll see the new WS-Transaction specification that was briefly covered in Chapter 8 supported within the BizTalk Server framework model.
EAN: 2147483647
Pages: 132