BizTalk Messaging Configuration Interfaces

The BizTalk Messaging Configuration object model enables programmers and administrators to manipulate and manage the BizTalk Messaging system in a programmatic fashion. This section discusses the interfaces in the Configuration object model as well as provides example code that demonstrates interface usage.

The sample code in this section is designed for Visual Basic/Visual Basic Script. The Visual Basic language was chosen for the sake of clarity and brevity. If you want to see sample C++ code, refer to the DistributionList sample that ships with BizTalk Server 2002.

Configuration Object Model Overview

The functionality exposed by the BizTalk Messaging Configuration object model closely replicates the functionality available in BizTalk Messaging Manager. This is no accident because BizTalk Messaging Manager is built directly on top of the Configuration object model. We're going to use this to our advantage as we learn the BizTalk Messaging Configuration object model by relating the properties and methods of each object to concepts we've already learned in BizTalk Messaging.

Table 19.1 lists the interfaces and associated objects exposed by the BizTalk Messaging Configuration object model.

IBizTalkConfig Interface

Programmatic access to the BizTalk Messaging system begins with the IBizTalkConfig interface. Through its methods, IBizTalkConfig acts as an object factory for the main BizTalk Messaging Configuration objects. The IBizTalkConfig properties serve as a central source for information about existing BizTalk Messaging objects. Table 19.2 lists the properties and methods exposed by the IBizTalkConfig interface.

The following sections discuss these properties and methods in greater detail.

Creating New BizTalk Messaging Configuration Objects

IBizTalkConfig exposes six methods for creating new BizTalk Messaging Configuration objects. Listing 19.1 shows these methods and their syntax.

Listing 19.1. Sample Configuration Object Creation Code

Set BT = CreateObject("BizTalk.BizTalkConfig")
Set org = BT.CreateOrganization
Set doc = BT.CreateDocument
Set env = BT.CreateEnvelope
Set port = BT.CreatePort
Set channel = BT.CreateChannel
Set group = BT.CreatePortGroup

Inspecting Existing BizTalk Messaging Objects

IBizTalkConfig exposes six properties that return ADO recordsets containing information about the BizTalk Messaging objects currently configured in the database. Listing 19.2 shows these properties and their syntax.

Listing 19.2. IBizTalkConfig BizTalk Messaging Object ADO Recordset Properties

Set BT = CreateObject("BizTalk.BizTalkConfig")
Set channel_rs = BT.Channels
Set doc_rs = BT.Documents
Set env_rs = BT.Envelopes
Set org_rs = BT.Organizations
Set group_rs = BT.PortGroups
Set port_rs = BT.Ports

Table 19.3 shows the fields returned by the ADO recordset properties.

Certificates

Certificates are used to authenticate and secure exchanges on nonsecured networks. Microsoft BizTalk Server relies heavily on the security provided by certificates. Public-key encryption is supported for all documents handled by BizTalk Server.

The IBizTalkConfig interface allows you to search the contents of a certificate store using the Certificates property. Table 19.4 shows the ADO recordset fields returned by the Certificates property.

Listing 19.3 demonstrates usage of the Certificates property.

Listing 19.3. Usage of the IBizTalkConfig Certificates Property

Set BT = CreateObject("BizTalk.BizTalkConfig")
Set rs = BT.Certificates(BIZTALK_STORE_TYPE_BIZTALK, BIZTALK_USAGE_TYPE_ENCRYPTION, "")

Do While Not rs.EOF
    MsgBox "Name: " & rs("name") & vbCRLF & _
           "Reference: " & rs("reference") & vbCRLF & _
           "Store: " & rs("store") & vbCRLF & _
           "Usage: " & rs("usage")
    rs.MoveNext
Loop

Note that the Certificates property is not a traditional property in that it takes several parameters. Those parameters in order are a BIZTALK_STORE_TYPE enumeration value, a BIZTALK_USAGE_TYPE enumeration value, and a prefix filter string to further refine your search.

Tables 19.5 and 19.6 show the possible values for the BIZTALK_STORE_TYPE and BIZTALK_USAGE_TYPE enumerations.

IBizTalkBase Interface

The IBizTalkBase interface, as its name suggests, exposes common properties and methods of the six primary BizTalk Messaging Configuration objects:

• BizTalkChannel

• BizTalkDocument

• BizTalkEnvelope

• BizTalkOrganization

• BizTalkPort

• BizTalkPortGroup

Table 19.7 lists the properties and methods of the IBizTalkBase interface.

Figure 19.3 shows the hierarchical relationship between IBizTalkBase and the six primary Configuration interfaces.

Creating New BizTalk Messaging Objects

BizTalk Messaging objects are created in the database by calling the Create method. Before calling Create, you must name the object:

Org.Name = "BizTalk Unleashed Organization" 
Org.Create

BizTalk Server places two restrictions on object names:

• The name must be at least one character and can be no more than 64 characters.

• The name, which is not case sensitive, must be unique across the database for the object type.

In addition, BizTalk Server reserved several names for BizTalk Messaging objects. Table 19.8 shows the names reserved by BizTalk Server 2002 and their associated object type.

When new objects are created in the database, BizTalk Server generates and assigns a unique internal handle value to the object. This value is static for the life of the object on this server. After calling Create, the Handle and DateModified properties are updated to

reflect the new object information.

Modifying BizTalk Messaging Objects

To change any of the settings for an existing BizTalk Messaging object, you must first load the object into memory. IBizTalkBase provides two methods for doing just that, Load and LoadByName. The following sample code demonstrates how to use these methods:

Org.Load hOrg   ' where hOrg is the handle to an organization 
Org.LoadByName "BizTalk Unleashed Organization"

After loading the object, you can make the necessary changes through the properties and methods of the Configuration object. Call the Save method to store your changes back to the database. The following code sample demonstrates an update to an organization in the database:

Org.LoadByName "BizTalk Unleashed Organization" 
Org.Name = "New BizTalk Unleashed Organization"
Org.CreateAlias "My Alias", False, "Qualifier", "Value"
Org.Save

After you call Save, the DateModified property is updated to reflect the new date and time.

Removing BizTalk Messaging Objects

To remove an object from the BizTalk Messaging database, first load the object into memory and then call Remove to delete the object from the database. For example:

Org.LoadByName "New BizTalk Unleashed Organization" 
Org.Remove

IBizTalkBase Example

Listing 19.4 shows a simple example illustrating the use of the IBizTalkBase properties and methods. Because a BizTalkBase object cannot be instantiated directly, a surrogate BizTalkOrganization object is used.

Listing 19.4. Visual Basic Code Illustrating the BizTalkBase Properties and Methods

' Step 1 - Create an organization configuration object
Set BT = CreateObject("BizTalk.BizTalkConfig")
Set org = BT.CreateOrganization()

' Step 2 - Name the organization and create it in the database
org.Name = "BizTalk Unleashed Organization"
hOrg = org.Create()
MsgBox "New object created, Handle = " & org.Handle & ", DateModified = " & org
.DateModified & "."

' Step 3 - Load our Organization by handle
org.Clear
org.Load hOrg
MsgBox org.Name & " loaded."

' Step 4 - Change the organization's name and save it back to the database
org.Name = "BizTalk Unleashed Sample Organization"
org.Save
MsgBox org.Name & " saved."

' Step 5 - Clear the config object and load our organization by name
org.Clear
org.LoadByName "BizTalk Unleashed Sample Organization"
MsgBox org.Name & " loaded."

' Step 6 - Remove our new organization from the database
org.Remove
MsgBox org.Name & " removed."

IBizTalkOrganization Interface

The IBizTalkOrganization interface exposes properties and methods that manage BizTalk Messaging organizations. Organizations represent trading partners with which you exchange documents. The Home Organization represents your business and may contain specific applications where inbound documents are routed. Table 19.9 shows the properties and methods of the IBizTalkOrganization interface.

In addition to the properties and methods shown in Table 19.9, BizTalkOrganization objects also implement the properties and methods of IBizTalkBase shown in Table 19.7.

Figure 19.4 shows a UML-style diagram illustrating the relationship between IBizTalkOrganization and IBizTalkBase.

The following sections discuss the properties and methods of the IBizTalkOrganization interface.

Aliases

Aliases are otherwise known as identifiers in BizTalk Messaging Manager. They specify qualifier-value pairs that uniquely identify an organization and consist of four properties:

• A handle that uniquely identifies the alias across the BizTalk Messaging database. Alias handles are assigned by BizTalk Server when the alias is created.

• A name unique across the organization object.

• An qualifier-value pair unique across the BizTalk Messaging database.

• A Boolean flag to indicate whether the alias is default.

Multiple aliases can be specified for a single organization; however, each alias name must be unique for the given organization. Alias qualifier-value pairs must be unique across all organizations in the database.

When new organizations are created, BizTalk Server automatically generates an alias with the name “Organization” and the qualifier-value pair, "OrganizationName"-<name of organization>. When an organization name is changed, BizTalk Server automatically updates the value in this qualifier-value pair to reflect the new organization name. Use the CreateAlias, LoadAlias, SaveAlias, and RemoveAlias methods to manipulate the current list of aliases for an organization. Listing 19.5 shows sample code that uses these methods. The handle value (100034) is made up for illustration purposes.

Listing 19.5. Sample Code for Manipulating Organization Aliases

org.CreateAlias "My Alias Name", False, "Alias Qualifier", "Alias Value"

Dim name, def, qual, val
org.LoadAlias 100034, name, def, qual, val

val = "New Alias Value"
org.SaveAlias 100034, name, def, qual, val

org.RemoveAlias 100034

You cannot remove auto-generated aliases, default aliases, or aliases referred to by BizTalk Messaging channels and/or ports.

The Aliases property returns an ADO recordset containing the current list of aliases in the organization. Table 19.10 shows the fields returned for each record.

Listing 19.6 shows example usage of the Aliases property.

Listing 19.6. Sample Code Illustrating the IBizTalkOrganization Aliases Property

Set BT = CreateObject("BizTalk.BizTalkConfig")
Set org = BT.CreateOrganization
org.LoadByName "Home Organization"
Set rs = org.Aliases

Do While Not rs.EOF
    MsgBox "ID: " & rs("id") & vbCRLF & _
           "Name: " & rs("name") & vbCrLf & _
           "Default: " & rs("defaultflag") & vbCRLF & _
           "Qualifier: " & rs("qualifier") & vbCrLf &_
           "Value: " & rs("value")
    rs.MoveNext
Loop

Applications

Applications in the Home Organization identify actual internal applications within your business. They do not, however, enable the flow of documents through BizTalk Messaging to the internal applications. Instead, they serve as placeholders to indicate a document destination. The actual configuration that enables the flow of documents to an application is specified by the transport properties of a messaging port.

BizTalk Messaging Manager only allows applications to be created in the Home Organization. The Configuration object model, however, does not enforce this rule. Therefore, any applications created in nondefault organizations cannot be manipulated in BizTalk Messaging Manager. Although creating applications outside the Home Organization is generally not recommended, it is possible to access and manipulate them through the Configuration object model.

Use the CreateApplication, LoadApplication, SaveApplication, and RemoveApplication methods to manipulate the current list of applications for an organization. Listing 19.7 shows sample code that uses these methods. Once again the handle value (100034) is made up for illustration purposes.

Listing 19.7. Sample Code for Manipulating Applications

org.CreateApplication "My Application Name"

Dim name
org.LoadApplication 100034, name

name = "New Application Name"
org.SaveApplication 100034, name

org.RemoveApplication 100034

An application cannot be removed if a BizTalk Messaging port or channel refers to it.

The Applications property returns an ADO recordset containing the current list of applications in the organization. Table 19.11 shows the fields returned for each record.

IBizTalkOrganization Example

Listing 19.8 demonstrates the creation of a new partner organization named Joe's Crab Shack.

Listing 19.8. Sample Script Demonstrating the Creation of a New Organization

' Create a new organization
Set BT = CreateObject("BizTalk.BizTalkConfig")
Set org = BT.CreateOrganization
org.Name = "Joe's Crab Shack"
org.Create

' Create an alias for the organization
org.CreateAlias "Best Crabcakes in Maryland", False, "Awards", "Best Crabcakes"
org.Save

' Add a new application to the home organization
org.Clear
org.LoadByName "Home Organization"
org.CreateApplication "Restaurant Reviews"
org.CreateApplication "My Application"
org.Save

IBizTalkDocument Interface

The IBizTalkDocument interface provides properties and methods for managing BizTalk Messaging document definitions. Document definitions represent specific types of documents handled by BizTalk Server. They consist of a BizTalk Server-specific XML document specification schema, which describes the content and format of the document. Table 19.12 shows the properties and methods of the IBizTalkDocument interface.

In addition to the properties and methods shown in Table 19.12, BizTalkDocument objects also implement the properties and methods of IBizTalkBase, shown in Table 19.7.

Figure 19.5 shows a UML-style diagram illustrating the relationships between IBizTalkDocument and various Configuration interfaces.

Document Specification

The document specification for a BizTalkDocument object is set by specifying the full WedDAV URL for the document specification file in the Reference property. For example:

doc.Reference = "http://machine/BizTalkServerRepository/DocSpecs/Microsoft/CommonPO.xml" 

When a document definition is created or saved using the Create or Save methods, the Content, NameSpace, Type, and Version properties are updated to reflect the new document specification. When Reference is empty, these properties are cleared.

Global Tracking

Document tracking data designates fields within the document specification that you want to log to the Tracking database. The TrackFields property is used to specify tracking data for a BizTalkDocument object. TrackFields returns a Dictionary object containing the custom fields that Tracking uses to track documents based on this specification. Tracking fields apply only to inbound documents in a channel. Any tracking data specified for an outbound document is ignored by BizTalk Server.

Table 19.13 shows the predefined Dictionary fields used by Tracking.

The fields in the dictionary must contain valid XPath values that identify the fields to be tracked. Listing 19.9 shows some example XPath expressions. The XPath expressions were derived from the CommonPO.xml document specification that ships with BizTalk Server.

Listing 19.9. Sample XPath Tracking Fields

doc.TrackFields.r_value1 = "/CommonPO/SpecialCharge/@Amount"
doc.TrackFields.r_value2 = "/CommonPO/Currency/@ExchangeRate"

doc.TrackFields.s_value1 = "/CommonPO/TermsOfSale/@PaymentMethod"
doc.TrackFields.s_value2 = "/CommonPO/CarrierDetail/@Routing"

doc.TrackFields.i_value1 = "/CommonPO/TermsOfSale/@NetDays"
doc.TrackFields.i_value2 = "/CommonPO/TermsOfSale/@DiscountDaysDue"

doc.TrackFields.d_value1 = "/CommonPO/Item/DateReference/@Date"
doc.TrackFields.d_value2 = /CommonPO/POHeader/@CreationDate

If additional fields are required, the x_custom_search field can be used. x_custom_search returns a SimpleList to which fields can be added or removed using the ISimpleList.Add and ISimpleList.Remove methods. Listing 19.10 shows sample code for the x_custom_search Dictionary field.

Listing 19.10. Sample Code for Custom Tracking Fields

doc.TrackFields.x_custom_search.Add "/CommonPO/Total/@LineItemTotal"
doc.TrackFields.x_custom_search.Add "/CommonPO/Total/@QuantityTotal"
doc.TrackFields.x_custom_search.Add "/CommonPO/Total/@POTotal"

doc.TrackFields.x_custom_search.Remove "/CommonPO/POHeader/@Purpose"
doc.TrackFields.x_custom_search.Remove /CommonPO/POHeader/@Type

Selection Criteria

Selection criteria are a set of unique name-value pairs used to process EDI documents. The PropertySet property is used to specify selection criteria for a BizTalkDocument object. PropertySet returns a Dictionary object with the EDI selection criteria for the document specification. Selection criteria is required for X12 and EDIFACT type document definitions.

Tables 19.14 and 19.15 show the required and optional header elements that must be specified for EDI document specifications.

IBizTalkDocument Example

Listing 19.11 shows sample code that creates a new document definition named Restaurant Reviewer based on the CommonPartnerProfile.xml document specification that ships with BizTalk Server. Before running this code on your machine, you need to change machine in the Reference WebDAV URL to the network name of the machine where your BizTalk Server is installed.

Listing 19.11. Sample Code to Create a New Document

' Create a new document specification
Set BT = CreateObject("BizTalk.BizTalkConfig")
Set doc = BT.CreateDocument
doc.Name = "Restaurant Reviewer"
doc.Reference = "http://machine/BizTalkServerRepository/DocSpecs/Microsoft
/CommonPartnerProfile.xml"
doc.Create

' Add tracking fields
doc.TrackFields.s_value1 = "/CommonPartnerProfile/Name/@Text"
doc.TrackFields.s_value2 = "/CommonPartnerProfile/Location/@AgencyCode"
doc.Save

IBizTalkEnvelope Interface

The IBizTalkEnvelope interface provides properties and methods for managing BizTalk Messaging envelopes. An envelope encapsulates electronic business data for transport into and out of BizTalk Server. Conceptually, it consists of a header and sometimes a footer and provides BizTalk Server with the necessary information to open inbound interchanges and create outbound documents.

The BizTalk Messaging envelope itself consists of a format type, which in turn may require an envelope specification. Table 19.16 shows the properties of the IBizTalkEnvelope interface.

In addition to the properties and methods shown in Table 19.16, BizTalkEnvelope objects also implement the properties and methods of IBizTalkBase, shown in Table 19.7.

Figure 19.6 shows a UML-style diagram illustrating the relationships between IBizTalkEnvelope and various Configuration interfaces.

Envelope Format

An envelope format is specified through the Format property. Format takes one of the following strings:

• x12

• edifact

• custom xml

• flatfile

• custom

• reliable

Specifying anything other than one of these strings results in a runtime error when Save or Create is called. If this occurs, the previously specified format is not changed. The following code sample shows correct and incorrect format specification strings:

env.Format = "edifact"    ' OK 
env.Format = "EDIFACT"    ' OK
env.Format = "flatfile"   ' OK
env.Format = "flat file"  ' Error

Notice that the format string is not case sensitive.

Envelope Specification

The conditionally required envelope specification is specified through the Reference property. Reference takes a string containing the full WebDAV URL for the envelope specification file. X12, EDIFACT, and reliable are well-known formats to BizTalk Server and as such do not need a specification file. The system goes so far as to throw a runtime error when Reference is set for one of these formats. Listing 19.12 shows correct and incorrect usage of the Reference property for an EDI envelope.

Listing 19.12. Correct and Incorrect Usage of the Reference Property for EDI Envelopes

' Incorrect:
Set BT = CreateObject("BizTalk.BizTalkConfig")
Set env = BT.CreateEnvelope
env.Name = "BizTalk Unleashed Envelope"
env.Format = "x12"
env.Reference = "http://machine/BizTalkServerRepository/DocSpecs/Envelope.xml"
env.Create ' Runtime error!

' Correct:
Set BT = CreateObject("BizTalk.BizTalkConfig")
Set env = BT.CreateEnvelope
env.Name = "BizTalk Unleashed Envelope"
env.Format = "x12"
env.Create

When an envelope is created or saved using the Create or Save methods, the Content, NameSpace, and Version properties are updated to reflect the new envelope specification. If Reference is empty, these properties are cleared to their default values.

IBizTalkEnvelope Example

Listing 19.13 shows an example that creates an envelope based on the Simple SOAP Envelope document specification that ships with BizTalk Server 2002.

Listing 19.13. Sample Code to Create a New Envelope

Set BT = CreateObject("BizTalk.BizTalkConfig")
Set env = BT.CreateEnvelope
env.Name = "Simple Soap Envelope"
env.Format = "custom xml"
env.Reference = "http://machine/BizTalkServerRepository/DocSpecs/Microsoft/ Simple SOAP
 Envelope.xml"
env.Create

IBizTalkPort Interface

The IBizTalkPort interface provides properties and methods for managing BizTalk Messaging ports. A BizTalk Messaging port defines the one-way transfer of a document between organizations and applications. Table 19.17 shows the properties and methods of the IBizTalkPort interface.

In addition to the properties and methods shown in Table 19.17, BizTalkPort objects also implement the properties and methods of IBizTalkBase shown in Table 19.7.

Figure 19.7 shows a UML-style diagram illustrating the relationships between IBizTalkPort and various Configuration interfaces.

Destination

Messaging port destinations specify where the messaging port delivers documents. Destinations can be organizations, XLANG schedules, or applications in the Home Organization. A messaging port destination is specified through the DestinationEndPoint property of the IBizTalkPort interface. DestinationEndPoint returns an instance of an object that implements the IBizTalkEndPoint interface. Table 19.18 shows the properties of the IBizTalkEndPoint interface.

Table 19.19 shows the possible enumeration values for the Openness property of the IBizTalkEndPoint interface.

The Alias and Organization properties can both be used for specifying a destination organization. It is not necessary to specify an alias and an organization, though; one or the other will suffice.

The following “Destination:” sections discuss the various messaging port destination types and the implications of using each type.

Destination: Organization

For destinations to organizations, the messaging port may specify a specific partner organization or leave the destination open, creating an open messaging port. Open messaging ports expect the destination information to be supplied at runtime through fields in the document or parameters passed during submission.

Before configuring a messaging port to an organization, the organization must be added to the BizTalk Messaging database. Listing 19.14 demonstrates the required settings for the DestinationEndPoint property to configure a messaging port to a specific partner organization.

Listing 19.14. DestinationEndPoint Settings for a Partner Organization

org.LoadByName "Joe's Crab Shack"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

Listing 19.15 demonstrates the required settings for the DestinationEndPoint property to configure an open messaging port.

Listing 19.15. DestinationEndPoint Settings for an Open Messaging Port

port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_DESTINATION

When creating open messaging ports, you must abide by the following constraints:

• PrimaryTransport.Type must be set to BIZTALK_OPENNESS_TYPE_OPENDESTINATION.

• EncryptionType cannot be set.

• The messaging port cannot be included in a distribution group.

Destination: XLANG Schedule

Messaging ports to XLANG schedules can be configured to activate a new XLANG schedule or deliver documents to a running XLANG schedule. Listing 19.16 demonstrates the required settings for the DestinationEndPoint property to configure a messaging port to activate an XLANG schedule.

Listing 19.16. DestinationEndPoint Settings for a Messaging Port to a New XLANG Schedule

org.LoadByName "Home Organization"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW

Listing 19.17 demonstrates the required settings for the DestinationEndPoint property to configure a messaging port to a running XLANG schedule.

Listing 19.17. DestinationEndPoint Settings for a Messaging Port to a Running XLANG Schedule

port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW

Notice that a destination to a running XLANG schedule does not require that an organization be specified. Information that identifies running XLANG schedules is passed in document fields as parameters during document submission.

Destination: Application

Before configuring a messaging port destination to an application, the application must be added to the Home Organization. Listing 19.18 demonstrates the required settings for the DestinationEndPoint property to configure a messaging port to an application.

Listing 19.18. DestinationEndPoint Settings for a Messaging Port to an Application

org.LoadByName "Home Organization"
Set rs = org.Applications
AppHandle = 0

Do While Not rs.EOF
    If (rs("name") = "My Application") Then
        AppHandle = rs("id")
        Exit Do
    End If
    rs.MoveNext
Loop

port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Application = AppHandle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

Transport

Messaging port transports specify the transport service that will be used to transport documents as well as the specific address to which documents are sent. Messaging port transports are specified through the PrimaryTransport and SecondaryTransport properties of the IBizTalkPort interface. Both properties return an instance of an object that implements the IBizTalkTransportInfo interface. Table 19.20 shows the properties of the IBizTalkTransportInfo interface.

Transport Type

The transport type is specified through the Type property of the IBizTalkTransportInfo interface. Table 19.21 shows the transport type enumeration values.

Transport type is closely tied to—and even constrained by—the destination type of the associated messaging port. For example, open messaging ports must specify BIZTALK_TRANSPORT_TYPE_OPENDESTINATION as their primary transport type.

Messaging ports that activate new XLANG schedules must set their primary transport type to BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION.

Transport Address

The transport address indicates the destination of the document and is specified through the Address property of the IBizTalkEndPoint interface. Table 19.22 shows the transport types that require an associated address as well as the address prefix required by the type.

Listing 19.19 shows example usage of the Type and Address properties for each available transport type in BizTalk Server.

Listing 19.19. Sample Transport Types and Addresses

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_APPINTEGRATION
port.PrimaryTransport.Address = "{11111111-1111-1111-1111-111111111111}"

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_FILE
port.PrimaryTransport.Address = "file://C:BizTalk UnleashedTest.xml"

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_HTTP
port.PrimaryTransport.Address = "http://www.samspublishing.com"

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_HTTPS
port.PrimaryTransport.Address = " https://www.samspublishing.com "

' Does not require Address
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_LOOPBACK

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_MSMQ
port.PrimaryTransport.Address = "DIRECT=OS:.private$myqueue"

' Does not require Address
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_NONE

' Does not require Address
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_OPENDESTINATION

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION
port.PrimaryTransport.Address = "C:BizTalk Unleashed	est.skx"

port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_SMTP
port.PrimaryTransport.Address = mailto:[email protected]

For the most part, there are no surprises in the sample addresses listed here. One exception may be the address for BIZTALK_TRANSPORT_TYPE_APPINTEGRATION. The APPINTEGRATION address specifies the CLSID of a registered COM+ AIC component.

Additional Transport Data

Some transport types require additional information beyond the transport address. Additional data is specified through the Parameter property of the IBizTalkTransportInfo interface. Table 19.23 shows which transport types require more information and what that information is.

Service Window

A service window indicates the valid time range as hours in the day for transmitting documents. A service window is specified through the ServiceWindowTransport property of the IBizTalkPort interface. ServiceWindowTransport returns an instance of an object that implements the IBizTalkServiceWindowInfo interface. Table 19.24 shows the properties of the IBizTalkServiceWindowInfo interface.

When setting a service window, you must specify a valid time range using the FromTime and ToTime properties of BizTalkServiceWindowInfo. Service window times must contain a value between 0 and 23 indicating the hour of the day. BizTalk Server does not provide support for fractional hours or minutes. Listing 19.20 shows sample code that uses the ServiceWindowTransport property.

Listing 19.20. ServiceWindowTransport Property Sample Code

' 7am to 7pm
port.ServiceWindowTransport.FromTime  = 7
port.ServiceWindowTransport.ToTime    = 19
port.ServiceWindowTransport.IsEnabled = True

The following sections will build on the samples started in the “Destination” section to include transport information.

Destination: Organization (ver HTTPS/HTTP)

Listing 19.21 demonstrates the required destination and transport settings to configure a messaging port to an organization over HTTPS (primary) and HTTP (secondary).

Listing 19.21. Transport Settings for a Messaging Port to an Organization over HTTP and HTTPS

org.LoadByName "Joe's Crab Shack"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_HTTPS
port.PrimaryTransport.Address = "https://secure.joescrabs.com"
port.SecondaryTransport.Type = BIZTALK_TRANSPORT_TYPE_HTTP
port.SecondaryTransport.Address = http://www.joescrabs.com

Destination: Organization (over SMTP)

Listing 19.22 demonstrates the required destination and transport settings to configure a messaging port to an organization over SMTP.

Listing 19.22. Transport Settings for a Messaging Port to an Organization over SMTP

org.LoadByName "Joe's Crab Shack"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_SMTP
port.PrimaryTransport.Address = "mailto:[email protected]"
port.PrimaryTransport.Parameter = mailto:[email protected]

Destination: Open Destination

Listing 19.23 demonstrates the required destination and transport settings to configure an open messaging port.

Listing 19.23. Transport Settings for an Open Messaging Port

port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_DESTINATION
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_OPENDESTINATION

Destination: New XLANG Schedule

Listing 19.24 demonstrates the required destination and transport settings to configure a messaging port to activate a new XLANG schedule.

Listing 19.24. Transport Settings for a Messaging Port to Activate a New XLANG Schedule

org.LoadByName "Home Organization"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION
port.PrimaryTransport.Address = "C:BizTalkSchedulesMySchedule.skd"
port.PrimaryTransport.Parameter = "start_port"

Destination: Running XLANG Schedule

Listing 19.25 demonstrates the required destination and transport settings to configure a messaging port to a running XLANG schedule.

Listing 19.25. Transport Settings for a Messaging Port to a Running XLANG Schedule

port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_OPENDESTINATION

Destination: Application (AIC)

Listing 19.26 demonstrates the required destination and transport settings to configure a messaging port to an Application Integration Component (AIC).

Listing 19.26. Transport Settings for a Messaging Port to an AIC

org.LoadByName "Home Organization"
Set rs = org.Applications
AppHandle = 0

Do While Not rs.EOF
    If (rs("name") = "My Application") Then
        AppHandle = rs("id")
        Exit Do
    End If
    rs.MoveNext
Loop

port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Application = AppHandle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_APPINTEGRATION
port.PrimaryTransport.Address = "{23A4973A-EF2F-11D2-BF2C-00C04F682DE1}"

Destination: Application (ASP)

Listing 19.27 demonstrates the required destination and transport settings to configure a messaging port to an ASP page.

Listing 19.27. Transport Settings for a Messaging Port to an ASP Page

org.LoadByName "Home Organization"
Set rs = org.Applications
AppHandle = 0

Do While Not rs.EOF
    If (rs("name") = "My Application") Then
        AppHandle = rs("id")
        Exit Do
    End If
    rs.MoveNext
Loop

port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Application = AppHandle
port.DestinationEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type = BIZTALK_TRANSPORT_TYPE_HTTP
port.PrimaryTransport.Address = http://www.mycompany.com/submit_review.asp

Envelope

An envelope consists of a header and sometimes a footer and provides BizTalk Server with the necessary information to open inbound documents and interchanges and to create outbound documents. When BizTalk Server processes an outbound document, the properties of the messaging port envelope are used to create an interchange by encapsulating the document. Envelopes are associated with messaging ports through the Envelope property of the IBizTalkPort interface.

env.LoadFromHandle "Simple SOAP Envelope" 
port.Envelope = env.Handle

Associating an envelope to a port is optional. If you do choose to use an envelope, the format of the envelope must agree with the format of the document that it contains. The document format is determined by the outbound document specification of the associated channel.

Control Number

An interchange control number is used to identify and track documents processed by the messaging port. You must specify an interchange control number when the associated envelope uses an X12 or EDIFACT format. The interchange control number is specified through the ControlNumberValue property of the IBizTalkPort interface. The value must be between 1 and 999999999.

port.ControlNumberValue = 42 

Delimiters

Delimiters specify which characters are used to separate data within the envelope and documents of an interchange. You must specify a delimiter when the associated envelope uses an X12 or EDIFACT format. Delimiter lists are set through the Delimiters property of the IBizTalkPort interface. A delimiter returns a Dictionary object. Table 19.25 shows the required delimiter identifiers for X12 and EDIFACT envelopes.

Security

The security settings in a messaging port apply to the messaging port as well as all associated channels. If different channels need different security arrangements, you must create separate messaging ports for each channel.

Encoding

The messaging port encoding type is specified through the EncodingType property of the IBizTalkPort interface. EncodingType takes one of the BIZTALK_ENCODING_TYPE enumeration values shown in Table 19.26.

port.EncodingType = BIZTALK_ENCODING_TYPE_MIME 

Specifying a custom encoding type implies that a custom encoding component is specified in the associated BizTalk Messaging channel.

Encryption

The messaging encryption type is specified through the EncryptionType property of the IBizTalkPort interface. EncryptionType takes one of the BIZTALK_ENCRYPTION_TYPE enumeration values shown in Table 19.27.

port.EncryptionType = BIZTALK_ENCRYPTION_TYPE_SMIME 

Specifying a custom encryption type implies that a custom encryption component is specified in the associated BizTalk Messaging channel.

Encryption Certificate

The EncryptionCertificateInfo property returns an instance of an object that implements the IBizTalkCertificateInfo interface. The BizTalkCertificateInfo object contains information about the certificate that encrypts the document. Table 19.28 shows the properties of the IBizTalkCertificateInfo interface.

The Reference and Store properties of the IBizTalkCertificateInfo interface together specify a unique certificate from the certificate store. The certificate reference can be obtained from the Certificates property of the IBizTalkConfig interface. The Store property takes one of the BIZTALK_STORE_TYPE enumeration values listed in Table 19.29.

The read-only Name and Usage properties of IBizTalkCertificateInfo reflect the certificate specified by the Reference and Store properties. Name contains the string name of the certificate, whereas Usage contains one of the BIZTALK_USAGE_TYPE enumeration values shown in Table 19.30.

For more information about certificates, refer to the “IBizTalkConfig Interface” section earlier in this chapter.

Signature Type

The SignatureType property specifies the type of digital signing and verification and accepts one of the BIZTALK_SIGNATURE_TYPE enumeration values shown in Table 19.31.

port.SignatureType = BIZTALK_SIGNATURE_TYPE_SMIME 

IBizTalkPort Example

Listing 19.28 shows example code that creates two types of messaging ports.

Listing 19.28. Sample Code for Messaging Port Creation

' Create the config objects
Set BT = CreateObject("BizTalk.BizTalkConfig")
set org = BT.CreateOrganization
Set port = BT.CreatePort

' Find the Review application handle
org.LoadByName "Home Organization"
Set rs = org.Applications
AppHandle = 0

Do While Not rs.EOF
    If (rs("name") = "Restaurant Reviews") Then
        AppHandle = rs("id")
        Exit Do
    End If
    rs.MoveNext
Loop

' Create a messaging port to the review request ASP page
port.Name = "Restaurant Review Requests"
port.Comments = "Messaging port for receiving requests to review a restaurant"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Application = AppHandle
port.DestinationEndPoint.Openness = 'BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type = 'BIZTALK_TRANSPORT_TYPE_HTTP
port.PrimaryTransport.Address = "http://www.mycompany.com/submit_review.asp"
port.Create

' Reset the objects
org.Clear
port.Clear

' Load Joe's orgnaization
org.LoadByName "Joe's Crab Shack"

' Create a messaging port to send reviews to Joe's
port.Name = "Joe's Review Results"
port.Comments = "Messaging port to send a review back to Joe"
port.DestinationEndPoint.Organization = org.Handle
port.DestinationEndPoint.Openness = 'BIZTALK_OPENNESS_TYPE_EX_NOTOPEN
port.PrimaryTransport.Type =' BIZTALK_TRANSPORT_TYPE_SMTP
port.PrimaryTransport.Address = "mailto:[email protected]"
port.PrimaryTransport.Parameter = "mailto:[email protected]"
port.Create

IBizTalkChannel Interface

The IBizTalkChannel interface provides properties and methods for managing BizTalk Messaging channels. A BizTalk Messaging channel configures BizTalk Messaging Services to process the documents that it receives. Table 19.32 shows the properties and methods of the IBizTalkChannel interface.

In addition to the properties and methods shown in Table 19.32, BizTalkChannel objects also implement the properties and methods of IBizTalkBase shown in Table 19.7.

Figure 19.8 shows a UML diagram illustrating the relationships between IBizTalkChannel and various Configuration interfaces.

Source and Destination

A channel source specifies where source documents come from. Just like messaging port destinations, channel sources can be organizations, XLANG schedules, or applications in the Home Organization. The channel source is specified through the SourceEndPoint property of the IBizTalkChannel interface. SourceEndPoint returns an instance of an object that implements the IBizTalkEndPoint interface. Refer to Table 19.18 for a list of IBizTalkEndPoint properties.

Source: Organization

For source organizations, the channel may specify a partner organization or leave the source open, creating an open channel. Before configuring a channel from an organization, the organization must be added to the BizTalk Messaging database. Listing 19.29 demonstrates how to configure the SourceEndPoint property for a channel from a specific partner organization.

Listing 19.29. SourceEndPoint Settings for a Channel from an Organization

org.LoadByName "Joe's Crab Shack"
channel.SourceEndPoint.Organization = org.Handle
channel.SourceEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

Listing 19.30 demonstrates how to configure the SourceEndPoint property to create an open channel from an organization.

Listing 19.30. SourceEndPoint Settings for an Open Channel from an Organization

channel.SourceEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_SOURCE

Source: XLANG Schedule

Channels from XLANG schedules are by definition open. Listing 19.31 demonstrates how to configure the SourceEndPoint property for an open channel from an internal XLANG schedule.

Listing 19.31. SourceEndPoint Settings for a Channel from an XLANG Schedule

org.LoadByName "Home Organization"
channel.SourceEndPoint.Organization = org.Handle
channel.SourceEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW

Source: Application

Before configuring a channel source from an application, the application must be added to the Home Organization. Listing 19.32 demonstrates how to configure the SourceEndPoint property for a channel from an internal application.

Listing 19.32. SourceEndPoint Settings for a Channel from an Application

org.LoadByName "Home Organization"
Set rs = org.Applications
AppHandle = 0

Do While Not rs.EOF
    If (rs("name") = "My Application") Then
        AppHandle = rs("id")
        Exit Do
    End If
    rs.MoveNext
Loop

channel.SourceEndPoint.Organization = org.Handle
channel.SourceEndPoint.Application = AppHandle
channel.SourceEndPoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

Destination

Channels are always associated with a specific messaging port or distribution list. The messaging port or ports within the distribution list specify the document destination. To associate a messaging port or distribution list with a channel, use the Port or PortGroup properties of the IBizTalkChannel interface. The following code demonstrates these properties:

port.LoadByName "Restaurant Review Requests" 
channel.Port = port.Handle

or

portgroup.LoadByName "My Port Group" 
channel.PortGroup = portgroup.Handle

One of these properties must be set when creating a new channel. In addition, the properties are mutually exclusive. After a BizTalk Messaging channel is created in the database, the port or distribution list association cannot be changed.

Valid Source-Destination Combinations

BizTalk Server 2002 supports a limited number of channel (source) and messaging port (destination) combinations. In the following list of valid combinations, internal application refers to an application listed in the Home Organization or an XLANG schedule:

• Trading partner to an internal application

• Internal application to a trading partner

• Internal application to internal application

• Internal application to distribution list

• Internal application to open destination

• Open source to internal application

• Trading partner to trading partner (where your BizTalk Server serves as an intermediary)

Inbound and Outbound Document Definitions

Document definitions enable a channel to translate documents between their native formats and an intermediate XML format. With the inbound document in the intermediate format, the channel can map, filter, and log document fields. Input and output document specifications are specified through the InputDocument and OutputDocument properties of the IBizTalkChannel interface. For example:

doc.LoadByName "Restaurant Reviewer" 
channel.InputDocument = doc.Handle
channel.OutputDocument = doc.Handle

Both properties are required when creating a new BizTalk Messaging channel, and neither can be changed after the channel is created. In the preceding sample, the inbound and outbound document definitions are the same. The implication is that a document map is not needed.

Control Number

If the envelope format of the associated messaging port is X12 or EDIFACT, then an interchange control number must be specified. Custom envelope formats sometimes require an interchange control number as well. Use the ControlNumberValue property of the IBizTalkChannel interface to specify a control number. Interchange control values are between 1 and 999999999.

Decrypting and Verifying Inbound Documents

Inbound document decryption certificates and digital signature verification certificates are specified through the DecryptionCertificateInfo and VerifySignatureCertificateInfo properties of the IBizTalkChannel interface, respectively. Both properties return an instance of an object that implements the IBizTalkCertificateInfo interface.

Refer to Table 19.28 for a list of IBizTalkCertificateInfo properties.

Signing Outbound Documents

Outbound documents can be signed by BizTalk Server using a digital signature certificate. To specify a signature certificate, use the SignatureCertificateInfo property of the IBizTalkChannel interface. This property returns an instance of an object that implements the IBizTalkCertificateInfo interface.

Refer to Table 19.28 for a list of IBizTalkCertificateInfo properties.

Mapping

Sometimes the format of the inbound document specification does not match the format of the outbound document specification. When this occurs, a map is needed to translate the inbound document into the format of the outbound document. Maps are created using BizTalk Mapper and are specified in the IBizTalkChannel interface through the MapReference property. MapReference takes a string containing the full WebDAV URL of the associated map file. For example:

channel.MapReference = http://somemachine/BizTalkServerRepository/Maps/map.xml 

Tracking

Document definitions can specify fields within the document that are logged to the Tracking database. Channels can override the fields specified by the document definition with a set of channel-specific tracking fields. When this occurs, the channel-specified fields are logged in lieu of the global tracking fields defined by the document specification.

To specify tracking fields in a channel, use the TrackFields property of the IBizTalkChannel interface. TrackFields returns an instance of the Dictionary object. Listing 19.33 shows sample code with XLANG tracking fields.

Refer to the “IBizTalkDocument Interface” section earlier in this chapter for more information about tracking fields.

Listing 19.33. Sample XPath Tracking Fields

channel.TrackFields.r_value1 = "/CommonPO/SpecialCharge/@Amount"
channel.TrackFields.r_value2 = "/CommonPO/Currency/@ExchangeRate"

channel.TrackFields.s_value1 = "/CommonPO/TermsOfSale/@PaymentMethod"
channel.TrackFields.s_value2 = "/CommonPO/CarrierDetail/@Routing"

channel.TrackFields.i_value1 = "/CommonPO/TermsOfSale/@NetDays"
channel.TrackFields.i_value2 = "/CommonPO/TermsOfSale/@DiscountDaysDue"

channel.TrackFields.d_value1 = "/CommonPO/Item/DateReference/@Date"
channel.TrackFields.d_value2 = "/CommonPO/POHeader/@CreationDate"

channel.TrackFields.x_custom_search.Add "/CommonPO/Total/@LineItemTotal"
channel.TrackFields.x_custom_search.Add "/CommonPO/Total/@QuantityTotal"
channel.TrackFields.x_custom_search.Add /CommonPO/Total/@POTotal

Filtering

A channel filter provides a mechanism for determining when a channel should be invoked. When BizTalk Server receives a document, the filtering expression is evaluated against the values of the specified fields in that document. If the expression evaluates to true, the channel is invoked. If the expression evaluates to false, the channel is not invoked.

Use the Expression property of the IBizTalkChannel interface to specify a filtering expression.

Logging

BizTalk Server allows channels to specify whether and how inbound and outbound documents are logged. To configure logging options, use the LoggingInfo property of the IBizTalkChannel interface. LoggingInfo returns an instance of an object that implements the IBizTalkLoggingInfo interface. Table 19.33 shows the properties on the IBizTalkLoggingInfo interface.

Overriding Messaging Port Defaults

BizTalk Server allows channels to override certain messaging port properties associated with the transport; the document serializer; and custom encoding, encryption, and signature verification. This functionality is exposed in the Configuration object model through the following IBizTalkChannel methods:

• GetConfigComponent

• GetConfigData

• SetConfigComponent

• SetConfigData

Each of these methods takes as a parameter a BIZTALK_CONFIGDATA_TYPE enumeration value. The value indicates the messaging data being requested or changed. Table 19.34 shows the BIZTALK_CONFIGDATA_TYPE enumeration values.

The GetConfigComponent method returns the CLSID of the associated component for the specified BIZTALK_CONFIGDATA_TYPE enumeration value.

The SetConfigComponent method sets the CLSID of the component associated with the messaging port. This method is used to specify components that implement custom encryption, encoding, or signature verification. SetConfigComponent is also used to specify a custom serializer when the messaging port envelope is set to the custom format. You cannot change the transport components associated with the messaging port.

The GetConfigData method returns a Dictionary object containing values specific to the configuration component returned by GetConfigComponent(). It is not necessary to get the CLSID of the configuration component before calling GetConfigData().

Transport Properties

Transport components are associated with messaging ports based on the transport type of the associated primary or secondary transport. The GetDataComponent method returns the CLSID of the associated transport component. Table 19.35 shows the transport components that ship with BizTalk Server 2002.

The transport component for AIC transports is the Application Integration Component itself.

A channel cannot override which transport component is associated by the messaging port. What can be changed are specific properties of the transport component. The following sections discuss the transport types that can be customized through the GetConfigData and SetConfigData methods.

HTTP/HTTPS

The settings associated with an HTTP/HTTPS transport on a messaging port only specify the destination URL. When the destination URL requires login information or BizTalk Server requires a proxy server (because the server itself sits behind a firewall), the configuration data in the associated channel must be used. Table 19.36 shows the dictionary fields used by the HTTP/HTTPS transport component.

SMTP

The settings associated with an SMTP transport on a messaging port specify only the destination and return e-mail addresses. The SetConfigData method allows a channel to specify SMTP server information, additional e-mail header values, and character sets. Table 19.37 shows the dictionary fields used by the SMTP transport component.

File

The settings associated with a File transport on a messaging port specify only the destination file. The SetConfigData method allows a channel to specify how the file should be written and to specify a Windows username and password. Table 19.38 shows the dictionary fields used by the File transport component.

MSMQ

The settings associated with an MSMQ transport on a messaging port specify only the destination queue. The SetConfigData method allows a channel to specify specific MSMQ properties. Table 19.39 shows the dictionary fields used by the MSMQ transport component.

Orchestration Activation

Table 19.40 shows the dictionary fields used by the orchestration activation transport component.

Application Integration Components

AIC components can specify their own dictionary fields as needed. There are no standard fields for AIC components. Refer to the AIC documentation for a list of appropriate dictionary fields.

Serializer Properties

Serializers are associated with messaging ports based on the format of an associated envelope. Use the SetDataComponent method to specify a custom serializer. Table 19.41 shows the serializers that ship with BizTalk Server 2002.

The EDIFACT and X12 document serializers expose Dictionary objects for customizing the serialization process via the GetConfigData method. Tables 19.42 and 19.43 show the dictionary fields for the built-in EDI serializers.

Encryption, Encoding, and Signature

Custom encryption, encoding, and signature verification requires that components that implement the custom functionality be specified through the SetConfigComponent method of the IBizTalkChannel interface. In addition, these custom components may expose customization options via a Dictionary object returned from GetConfigData.

IBizTalkPortGroup Interface

The IBizTalkPortGroup interface provides properties and methods for managing BizTalk Messaging distribution lists. A BizTalk Messaging distribution list is a group of BizTalk Messaging ports that enable BizTalk Server to deliver a single document to multiple destinations with a one-document submission. Table 19.44 shows the properties and methods of the IBizTalkPortGroup interface.

In addition to the properties and methods shown in Table 19.44, BizTalkPortGroup objects also implement the properties and methods of IBizTalkBase shown in Table 19.7.

Figure 19.9 shows a UML-style diagram illustrating the relationships between IBizTalkPortGroup and various Configuration interfaces.

Adding Ports

BizTalk Server enforces two rules when adding ports to a distribution list:

• The messaging port Openness property must be set to BIZTALK_OPENNESS_TYPE_EX_NOTOPEN.

• Duplicate ports cannot be added to the same distribution list.

Use the AddPort method of the IBizTalkPortGroup interface to add a port to the distribution list. The following sample code demonstrates how to add a port to a distribution list:

port.LoadByName "Restaurant Review Requests" 
group.AddPort = port.Handle
group.Save

Removing Ports

Use the RemovePort method of the IBizTalkPortGroup interface to remove a messaging port from a distribution list. The following sample code demonstrates how to remove a port from a distribution list:

port.LoadByName "Restaurant Review Requests" 
group.RemovePort = port.Handle
group.Save