The RouteTest Application
The RouteTest example simulates the submittal of an XML purchase order for a company named General Construction Company (GCC) to a company named Knots Lumber. The XML purchase order created by GCC is submitted to a BizTalk server that's responsible for the transformation and transport of the XML document to Knots Lumber in Knots Lumber's XML purchase order format (slightly different from GCC's).
To simulate the purchase order system, we have written a Visual Basic 6.0 application that allows you to select from up to seven different scenarios that implement the IInterchange::Submit() method.
Each scenario specifies a different set of IInterchange::Submit() parameters to demonstrate the multiple BizTalk Messaging document routing possibilities. The RouteTest application consists of two forms and one class module that are described in the following sections. To run the application, you will also need to configure BizTalk Messaging document definitions, ports, and channels.
The RouteTest application is referenced throughout this chapter, and its setup is described in detail in the following section. The source code for the RouteTest application can be downloaded from the publisher's Web site.
The RouteTest Visual Basic Application
The RouteTest Visual Basic application consists of two forms and a class module. The forms and class module contents are described in detail in the following sections.
The frmRouteTest Visual Basic Form
The frmRouteTest form, shown in Figure 12.3, is used to select from a list of seven independent scenarios that demonstrate calling the IInterchange::Submit() method. Each scenario calls a method named SubmitInterchange that configures the Interchange:Submit() parameters at runtime.
Figure 12.3. The RouteTest application.
Listing 12.4 shows the source code for the form.
Listing 12.4. The frmRouteTest.frm Code
' *****************************************************************************
' FILE: frmRouteTest.frm
' *****************************************************************************
Dim oParams As New CInterchangeParams
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' SUB: Form_Load()
'
' Handle a change in the selected scenario
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Private Sub ctlRouteTest_Click()
Select Case ctlRouteTest.Text
Case "Scenario #1"
With oParams
.Scenario = "Sends a purchase order from GCC to KnotFree Lumber A channel
|
is hard-coded into the Interchange::Submit() call."
.Lesson = "Call-based routing." + vbCrLf + "Non-default Source Qualifiers"
.Openness = BIZTALK_OPENNESS_TYPE_NOTOPEN
.Document = ""
.DocDef = ""
.SrcQualifier = ""
.SrcID = ""
.DestQualifier = ""
.DestID = ""
.Channel = "PO_GCC-KF"
.FilePath = "C:RouteTestRuntimeSourceInst_PO_KnotFree_1.xml"
.Envelope = ""
.PassThrough = 0
PopulateForm
End With
Case "Scenario #2"
With oParams
.Scenario = "*Demonstrates ERROR CONDITION* : A channel is hard-coded into
The frmTracking Visual Basic Form
The frmTracking form, shown in Figure 12.4, displays three grids reflecting the return values of three IBizTalkTrackData interface methods.
Figure 12.4. The RouteTest Interchange Tracking screen.
The GetInterchanges method returns an ADO record set that contains a list of interchanges for a SubmissionHandle. The SubmissisonHandle is returned from a call to the IInterchange::Submit() method and includes data from the tracking database. The GetInDocDetails method returns an ADO record set that contains specific information about the input document(s) again based on the SubmissionHandle returned from the IInterchange::Submit() method. The GetOutDocDetails method returns an ADO recordset that contains information about the output document(s) for the submission handle.
The CInterchangeParams Class Module
The CInterchangeParams class module is used to construct a parameter list for the IInterchange::Submit method call. The parameters are filled by the frmRouteTests' private subroutine ctlRouteTest_Click() whenever the user chooses a scenario. This parameter class object has its values extracted in the SubmitInterchange method when IInterchange::Submit is called.
Setting Up BizTalk Messaging
The RouteTest application processes purchase orders for a construction company named General Construction Company (GCC). GCC sends purchase orders to a lumber company named Knot Lumber. Both organizations accept XML purchase orders; however, the schemas are slightly different. To accommodate the Knot Lumber format, GCC has configured a BizTalk Server to process, transform, and route purchase orders to Knot Lumber. The RouteTest Visual Basic application simulates the GCC purchase order system that creates a purchase order and then submits it to BizTalk Server for transformation and transport. To keep the example simple, the Knot Lumber Company accepts the purchase order via the file transport protocol.
To run the sample RouteTest application, we need to configure BizTalk Messaging document definitions, ports, channels, and organizations. In the following section, we will
Execute a script that copies the source code document specs and maps to the BizTalk repository.
Create the document definitions and map.
Create the organizations needed.
Create a channel and port.
Note
Additional message ports and channels will be created throughout the chapter to demonstrate the different routing techniques available.
Table 12.2 shows a list of document definitions and organizations that we will set up in the next few steps.
| Document Definitions: | Name: Spec_PO_GCC |
| Reference: <WebDAV>Spec_PO_GCC.xml | |
| Name: Spec_PO_KF | |
| Reference: <WebDAV>Spec_PO_KF.xml | |
| Organizations: | Name: Rename the Home Organization to General Construction Company |
| Custom Name: OrganizationGCC | |
| Qualifier: OrganizationGCC | |
| Value: GCC | |
| Name: Knots Lumber | |
| Custom Name: OrganizationKnotsLumber | |
| Qualifier: OrgKnotsLumber | |
| Value: KnotsLumber | |
| Port | Name: PortFromGCCtoKnotsLumber |
| Destination Organization: Knots Lumber | |
| Primary Transport: File (to C:RouteTestRuntimeDestKnotFreePO.xml) | |
| Channel | Type: To an Application |
| Name: PO_GCC-KF | |
| Source Application: GCC App | |
| Inbound Doc Spec: Spec_PO_GCC | |
| Outbound Doc Spec: Spec_PO_KF | |
| Map: <WebDAV>Map_PO_GCC-KFSelfRouting.xml |
Before we can configure BizTalk Messaging, we need to first create the document specifications and maps required to process the XML purchase order.
Copying the Document Specifications and Map
The document specification and maps needed for the RouteTest example have been created for you and can be downloaded from the publisher's Web site. There are two XML document specifications, SPEC_PO_GCC.xml and SPEC_PO_KF.xml, as shown in Figures 12.5 and 12.6.
Figure 12.5. The SPEC_PO_GCC General Construction Company XML purchase order specification.
Figure 12.6. The SPEC_PO_KF Knots Lumber XML purchase order specification.
Because the specifications represent different XML purchase order documents, we need to create a map to transform the General Construction Company's purchase order into the Knot Lumber format. The map is named MAP_PO_GCC-KFSelfRouting.xml and is displayed in Figure 12.7.
Figure 12.7. The GCC to KF purchase order map.
To run the example, download these documents as well as the RouteTest application source code from the publisher's Web site and unzip it onto your C: drive. This creates a directory with the associated source code named RouteTest. Then execute the VBScript file, CopyDocSpecsAndMap.vbs, located in the C:RouteTest directory. This script places the document specifications and maps located in the C:RouteTestSetupDocs and C:RouteTestSetupMaps directory into your :Program FilesMicrosoft BizTalk ServerBizTalk Server RepositoryDocs and :Program FilesMicrosoft BizTalk ServerBizTalk Server Repository Maps directories.
Note
To ensure that the directory structure is set up correctly under C:RouteTest, after you open the 12SampleRouteTest.zip, make sure that when you extract the files you set the Extract To edit field to C:and select the Use Folder Names check box.
If you unzip the source code into some other directory location, or if you have BizTalk installed on a hard drive other than the C: drive, you will need to manually edit the CopyDocSpecsAndMap.vbs file before you execute it.
Creating Document Definitions
Next, we need to create the document definitions for the purchase order specifications in the RouteTest example. To accomplish this, open the BizTalk 2002 Messaging Manager by selecting Start, Programs, Microsoft BizTalk Server 2002, BizTalk Messaging Manager from the menu. Then, click on the Document Definitions hyperlink in the left pane of the window. Now, click on the Search Now button. This displays all available document definitions in the right-hand pane.
To create a new document definition, select File, New, Document Definition from the menu. Figure 12.8 displays the New Document Definition dialog.
Figure 12.8. Creating a new document definition.
In the Document Definition Name edit field, type in the name Spec_PO_GCC and select the Document Specification check box. Now, select the Browse button. This will allow you to browse to your WebDAV server where you will find your document specification. Your WebDAV browser should look like Figure 12.9.
Figure 12.9. Choosing a document specification from WebDAV.
Select the document specification Spec_PO_GCC.xml, select Open, and then click OK. To create the second document definition, repeat the previous steps, but this time, the name of the document definition will be Spec_PO_KF, and the WebDAV document specification that it points to will be Spec_PO_KF.xml.
Creating the Organizations
The RouteTest application uses two organizations and one internal application. We will rename our default Home Organization to General Construction Company and create an application name for it. We will then create a new organization named Knots Lumber.
With the BizTalk Messaging Manager still open from the previous procedure, select the Organizations hyperlink in the left-hand pane and then select the Search Now button. A list of organizations will be displayed in the right pane. One of the organizations will have the name of an organization (probably Home Organization) and the word (default) in parentheses adjacent to it. This is your default home organization. Double-click on the Home Organization. This brings up the Organization Properties dialog.Change the name to General Construction Company. Next, click on the Identifiers tab. This is where you will set up your organizational names and identifiers. Figure 12.10 displays the Organization Properties dialog with the Identifiers tab selected.
Figure 12.10. Adding an identifier to an organization
Select the Add button. In the Custom edit field, enter the name OrganizationGCC. In the Qualifier field, enter the name OrganizationGCC. In the Value field enter the name GCC. Click OK when you have finished. Figure 12.11 shows the Identifiers Properties dialog.
Figure 12.11. Adding Identifier properties.
Next, we have to create an internal application that represents our GCC organization. Select the Organization Properties Applications tab and then select the Add button. Figure 12.12 shows the New Application dialog. Enter the name GCC App and click OK. Click OK in the Organization Properties dialog box.
Figure 12.12. Adding an application to the Home Organization.
Next, we will create a new organization, Knots Lumber. Select File, New, Organization from the menu. The New Organization dialog appears. In the Organization Name field, enter Knots Lumber. Click on the Identifiers tab. Here, we will set up the organizational names and identifiers specific to the Knots Lumber organization. Select Add. In the Custom field, enter OrganizationKnotsLumber. In the Qualifier field, enter OrgKnotsLumber. In the Value field enter KnotsLumber. Click OK when you are finished. Click OK in the New Organization dialog.
Now that we have configured the documents and organizations that are going to exchange purchase orders, we need to configure a port and channel to process them.
Creating the Messaging Port and Channel
The messaging port will be used to deliver our document to the Knots Lumber organization. To create the port, open the BizTalk Messaging Manager and select the Messaging Ports hyperlink. Then click the Search Now button. Select File, New, Messaging Port, To an Organization from the menu. The New Messaging Port window appears as shown in Figure 12.13.
Figure 12.13. The New Messaging Port Wizard.
In the Name field, enter PortFromGCCtoKnotsLumber and then click Next. Next, select the Browse button located adjacent to the Organization Name field. Figure 12.14 shows the New Messaging Port Destination Organization window.
Figure 12.14. The New Messaging Port Wizard Destination Organization page.
When the Browse button is selected, the Select an Organization dialog appears. Select the Knots Lumber organization and click OK. Figure 12.15 shows the Select an Organization dialog.
Figure 12.15. Selecting a destination organization.
On the New Messaging Port Destination Organization window, select the Browse button located adjacent to the Primary Transport Address field. Figure 12.16 shows the Primary Transport dialog box. Select File from the Transport Type drop-down list and then enter the following string in the Address field file://C:RouteTestRuntimeDestKnotFreePO.xml. It is important that you do not leave off the file:// part of this string. Click OK.
Figure 12.16. Setting up the primary transport.
By entering this pathname, we are telling the port to send our transformed document to the path and filename shown previously. Be sure to remember that if you run a document through the port more than once, it will append the data to the file that is already there. If there is no PO.xml file already there, one will be created.
Then click Next, accept the default settings on the Envelope Information page, and click Next again. On the Security Information page shown in Figure 12.17, the only change you need to make is in the Channel Type drop-down list. Select From an Application.
Figure 12.17. Selecting a channel from an application.
Click Finish. The New Channel Wizard first window appears as shown in Figure 12.18.
Figure 12.18. The New Channel Wizard.
In the Name field, enter PO_GCC-KF and click Next.
The next screen is the New Channel, Source Application screen shown in Figure 12.19. If GCC App is not currently selected in the Application Name edit field, use the drop-down box to select it and click Next.
Figure 12.19. Selecting a source application.
On the New Channel, Inbound Document screen, select the Browse button. This opens the Select a Document Definition dialog. Select the Spec_PO_GCC document definition and then click OK. Then, click Next. This brings you to the New Channel Outbound Document screen. Select the Browse button adjacent to the Outbound Document Definition Name field and then, from the Select a Document Definition dialog, select the Spec_PO_KF definition. Click OK. Your New Channel Outbound Document screen should now look like Figure 12.20.
Figure 12.20. The outbound document definition selected.
Notice how the Map Inbound Document to Outbound Document check box is automatically selected for you. This is because the New Channel Wizard recognized that your inbound document definition name on the previous screen is different from the outbound document definition name. Select the Browse button adjacent to the Map Reference edit field. Your WebDAV explorer screen appears. Select the map Map_PO_GCC-KFSelfRouting.xml, click Open, and click Next. On the Document Logging screen, deselect the Log Inbound Document In Native Format check box and click Next. On the Advanced Configuration screen, do not change any of the defaults and select Finish.
Running the RouteTest Example
Running the example is simple. To run the RouteTest.vbp application, open the RouteTest.vbp project using Visual Basic 6.0 and then select the Run menu option's Start menu option. The BizTalk Interchange Generator window appears. Then select a scenario in the drop-down list box and click Submit. The code will submit an XML purchase order named Inst_PO_KnotFree_1.xml to the BizTalk Server Messaging Engine. Listing 12.5 displays the Inst_PO_KnotFree_1.xml file.
Listing 12.5. The Inst_PO_KnotFree_1.xml Purchase Order
<PurchaseOrder>
<Vendor id="3005" name="Knotfree Lumber"/>
<Item sku="1425A3X">
<Item.Name>Pine 2x4x10</Item.Name>
<Item.Quantity>75</Item.Quantity>
<Item.PPU>1.20</Item.PPU>
</Item>
<Item sku="1847B2Z">
<Item.Name>Cedar TG</Item.Name>
<Item.Quantity>120</Item.Quantity>
<Item.PPU>4.59</Item.PPU>
</Item>
</PurchaseOrder>
|
This XML instance is used for every scenario except 6 and 7. The input documents for those scenarios are described in the “Dynamic Routing” section later in the chapter. Before going into depth about the different scenarios available in the RouteTest application, let's first discuss how BizTalk Server handles error processing.
Any type of error that occurs when BizTalk is processing a document should be considered a serious error. When BizTalk throws an error, the document will more than likely be placed into the suspended queue. Regardless of where the document is put, unless you are specifically looking at the Application Event Viewer, you might never know that an error was raised. Therefore, it is important to consistently monitor this event viewer either programmatically or manually.
The scenarios represented in the Message Routing section display errors in a variety of fashions, some appear on the screen and require a response (bad news for a server product), others go to the Application Event Viewer. The descriptions of the scenarios will tell you where to expect to receive the error.
Although the RouteTest application doesn't cover all of them, to give you a better idea of just how many permutations are possible, Table 12.3 lists all possible permutations for the IInterchange::Submit() parameters critical to the routing process.
| Id | lOpenness | DocName | SrcID | DestID | Channel | Valid |
|---|---|---|---|---|---|---|
| 1 | NOTOPEN | Empty | Empty | Empty | Empty | |
| 2 | NOTOPEN | Empty | Empty | Empty | Valid | Yes |
| 3 | NOTOPEN | Empty | Empty | Valid | Empty | |
| 4 | NOTOPEN | Empty | Empty | Valid | Valid | No |
| 5 | NOTOPEN | Empty | Valid | Empty | Empty | |
| 6 | NOTOPEN | Empty | Valid | Empty | Valid | No |
| 7 | NOTOPEN | Empty | Valid | Valid | Empty | |
| 8 | NOTOPEN | Empty | Valid | Valid | Valid | No |
| 9 | NOTOPEN | Valid | Empty | Empty | Empty | |
| 10 | NOTOPEN | Valid | Empty | Empty | Valid | No |
| 11 | NOTOPEN | Valid | Empty | Valid | Empty | |
| 12 | NOTOPEN | Valid | Empty | Valid | Valid | No |
| 13 | NOTOPEN | Valid | Valid | Empty | Empty | |
| 14 | NOTOPEN | Valid | Valid | Empty | Valid | No |
| 15 | NOTOPEN | Valid | Valid | Valid | Empty | |
| 16 | NOTOPEN | Valid | Valid | Valid | Valid | No |
| 17 | SOURCE | Empty | Empty | Empty | Empty | |
| 18 | SOURCE | Empty | Empty | Empty | Valid | |
| 19 | SOURCE | Empty | Empty | Valid | Empty | |
| 20 | SOURCE | Empty | Empty | Valid | Valid | |
| 21 | SOURCE | Empty | Valid | Empty | Empty | |
| 22 | SOURCE | Empty | Valid | Empty | Valid | |
| 23 | SOURCE | Empty | Valid | Valid | Empty | |
| 24 | SOURCE | Valid | Empty | Empty | Valid | |
| 25 | SOURCE | Valid | Empty | Empty | Empty | |
| 26 | SOURCE | Valid | Empty | Valid | Valid | |
| 27 | SOURCE | Valid | Valid | Empty | Empty | |
| 28 | SOURCE | Valid | Valid | Empty | Valid | |
| 29 | SOURCE | Valid | Valid | Valid | Empty | |
| 30 | DEST | Empty | Empty | Empty | Valid | |
| 31 | DEST | Empty | Empty | Empty | Empty | |
| 32 | DEST | Empty | Empty | Valid | Valid | |
| 33 | DEST | Empty | Empty | Valid | Empty | |
| 34 | DEST | Empty | Valid | Empty | Valid | |
| 35 | DEST | Empty | Valid | Valid | Empty | |
| 36 | DEST | Empty | Valid | Valid | Valid | |
| 37 | DEST | Valid | Empty | Empty | Empty | |
| 38 | DEST | Valid | Empty | Valid | Valid | |
| 39 | DEST | Valid | Empty | Valid | Empty | |
| 40 | DEST | Valid | Valid | Empty | Valid | |
| 41 | DEST | Valid | Valid | Valid | Empty | |
| 42 | DEST | Valid | Valid | Valid | Valid |
Note
The permutations listed in Table 12.3 assume that the PassThrough parameter is set to False.
We have now successfully configured BizTalk Messaging for several of the RouteTest example scenarios. In the following sections we will discuss the different types of routing available.