BizTalk Messaging Overview

Before discussing the BizTalk Messaging Configuration object model, it is useful to have a conceptual understanding of BizTalk Messaging. This section provides a high-level overview of BizTalk Messaging. Refer to Chapter 6, “Introduction to BizTalk Messaging,” and Chapter 12, “Advanced BizTalk Messaging,” for an in-depth discussion of BizTalk Messaging.

BizTalk Messaging

BizTalk Messaging is a set of services that provide a mechanism for routing documents in an enterprise environment. These services allow you to define how documents are received, processed, and delivered. In addition, you can specify settings for data mapping, integrity, security, document tracking, and receipt generation. In short, think of BizTalk Messaging as the glue that ties many disparate systems together in an enterprise messaging environment.

Configuration Objects Versus BizTalk Messaging Objects

This chapter refers to two types of objects:

• BizTalk Messaging objects

• BizTalk Messaging Configuration objects

BizTalk Messaging objects are the actual objects stored in the BizTalk Messaging database. BizTalk Messaging Configuration objects are the COM objects exposed by the BizTalk Messaging Configuration object model. Configuration objects are used to create, inspect, modify, and remove BizTalk Messaging objects in the database.

Figure 19.1 shows the relationships established by BizTalk Messaging objects. This UML-style diagram uses solid lines terminated with a diamond arrow to indicate associations between objects. The arrow direction indicates which object makes the association. For example, ports establish associations with envelopes. The numbers at either end indicate how many associations can be made. For example, a port may specify up to one envelope, whereas an envelope may have any number of ports (including none) that refer to it.

Figure 19.2 shows the relationships established by the BizTalk Messaging Configuration object model. Notice that the associations shown in Figure 19.1 are still in place in the Configuration object model.

Figure 19.2 shows three types of relationships:

• Inheritance— Indicated by a dotted arrow from the derived interface to the base interface

• Dependency— Indicated by a dashed arrow from an object to the object it uses

• Association— Indicated by a solid arrow (terminated with a diamond) from the object that makes an association to the object that is associated

If Figure 19.2 looks a little confusing, don't worry. We will discuss each of the major Configuration objects later in this chapter. At that time, we'll break down this diagram to include only those parts that pertain to a particular object and include the properties and methods that establish or report these relationships.

Referential Integrity

The term referential integrity means that one BizTalk Messaging object cannot be deleted while another BizTalk Messaging object maintains a reference to it. An object that maintains a reference to another object is said to have a referential dependency on that object.

There are two approaches to removing referential dependencies. The first approach is to change which BizTalk Messaging object is referenced within the referring object. For instance, you could change the inbound document specification referenced by a channel object. This is not always possible, though, because many references cannot be changed after the object is created. That leads to the second approach, which is to delete the referring object altogether.

To avoid problems when removing BizTalk Messaging objects, remove them in the opposite order of creation. BizTalk Server recommends that BizTalk Messaging objects be created in the following order:

• Organizations

• Document specifications

• Envelopes

• Ports

• Channels

• Distribution lists

When deleting BizTalk Messaging objects, remember that organizations, document specifications, envelopes, and ports could have any number of referential dependencies in place and that all object references must be removed before the object itself can be removed.

Security

During installation, Microsoft BizTalk Server 2002 creates a Windows 2000 User Group named BizTalk Server Administrators. To access any of the objects in the BizTalk Messaging Configuration object model, a script or application must be run in the context of a user account that is a member of the BizTalk Server Administrators group. An access denied error (0x80070005) is returned when the user account is not a member of this group.

A scenario where this error occurs but the cause is not obvious is when the BizTalk Messaging Configuration object model is accessed through Web Services or a Web page running under Internet Information Services (IIS). The default user account for anonymous access in IIS is IUSR_MACHINE, where MACHINE is typically the network name for your computer. It is, of course, highly recommended that you secure all BizTalk Messaging Configuration access through Web-based applications; however, for testing, you could make the IUSER_MACHINE account a member of the BizTalk Server Administrators group.

Documentation

Microsoft BizTalk Server 2002 ships with two types of documentation: online help and samples. The online help contains everything from conceptual overviews and tutorials to bare metal explanations of BizTalk Messaging. This includes the Configuration object model reference, which is located under “BizTalk Server 2002 Developer Solutions/BizTalk Server Reference/Messaging Services Reference.”

In addition to the online help, BizTalk Server 2002 ships with many useful BizTalk Messaging samples. The samples are located in the Microsoft BizTalk ServerSDKMessaging Samples directory. Most of the samples do not pertain directly to the Configuration object model; however, they still contain useful sample code in the form of setup scripts.

The setup scripts create and configure the necessary BizTalk Messaging objects required to run the associated sample. Most of the scripts were generated using a legacy tool named BizPort. You'll see odd variable names such as lOrg110047 (formed by concatenating “l” for long, “Org” for a BizTalk Messaging organization, and the organization handle value) and related functions such as Create_lOrg110047. That being said, the setup scripts are still useful, especially when you consider what the sample itself is doing. For example, you can use the config.vbs script in the BizTalk ServerAppIntegrate sample as a guide for configuring BizTalk Messaging for Application Integration Components (AIC).

One sample that applies specifically to BizTalk Messaging Configuration is BTConfigAssistant. The BTConfigAssistant sample allows users to select and export BizTalk Messaging objects in the form of a configuration VBScript. The sample itself is a direct consumer of the Configuration object model.

A word of caution to those using the BTConfigAssistant sample to reproduce BizTalk Messaging configurations on other BizTalk servers. The BTConfigAssistant sample is not supported by Microsoft and doesn't always work as intended. In fact, the functionality of this sample may be superceded by the SEED Wizard. In other words, use BTConfigAssistant as an example for code that consumes the BizTalk Messaging Configuration object model.

For the hard-core programmers, the DistributionList sample includes usage of the object model in C++. The properties and methods exposed by the object model are no different for C++, but the sample does include all the messy COM overhead code required in C++.

One last code resource is the Microsoft BizTalk ServerSDKInclude directory. Here you will find the idl and header files for the BizTalk Messaging Configuration object model as well as other BizTalk Server object models.