Sample Chapter from the book BizTalk Server 2000 Developer’s Guide for .NET. Reprinted by permission, Syngress Publishing © 2002.

Using The Channel Wizard

The Channel wizard is the method of choice for creating a new channel from the BizTalk Messaging Manager user interface. There are several ways to initiate this wizard:

·     Create a new messaging port, making sure the Create a channel for this messaging port check box is checked. If it is checked, the Channel wizard will be started immediately after the messaging port configuration is finished.

·     Select an existing messaging port, and then right-click the port to get the pop-up context menu. Choose New channel from the menu, and then choose either From an organization or From an application.

·     Select an existing distribution list and perform the same actions as above.

The Channel wizard appears the same regardless of whether you’re creating a new channel for the first time or editing an existing channel, so it’s always possible to go back and edit any configuration problems that you might accidentally introduce into a channel. The initial screen of the Channel wizard allows you to set a friendly name and some comments for the new channel, as shown in Figure 4.12.

Figure 4.12 Creating a New Channel

The next screen in the wizard allows you to configure the source organization (or specify “open source”), and specify whether to expect or generate receipts, as shown in Figure 4.13.

Figure 4.13 Setting the Channel’s Source Properties

Specifying an organization name and an associated identifier in this screen allows the channel to receive only those documents that contain that organization’s identifier in the BizTalk header. If “Open source” is selected, then other, dynamic criteria are used to decide if this channel should accept a particular instance document. In addition, “Expect receipt” signifies that our BizTalk Server will request that the destination server reply to this document with a receipt.

Finally, “Generate receipt” should be selected only if the type of document handled by this channel requires a receipt to be generated. If so, the corresponding, preconfigured receipt channel should also be selected here.

The next screen (Figure 4.14) acquires information about the inbound document. The inbound document definition is specified in the first text box, and the inbound instance document is validated against any document specification referenced by this definition. In addition, for any channels that are configured as open source, this document definition is used in part to help decide whether this channel is an acceptable target for this instance document. If the instance document is properly validated by the document definition, then this channel can be an acceptable target for the document. In addition, several security-related options are given, to decrypt the document content or verify its digital signature. Finally, both tracking and filtering options are given, as explained in the previous sections.

Figure 4.14 Configuring the Channel’s Inbound Document Type

Similar to the inbound document page of the wizard, the next screen contains information pertaining to the destination document format (Figure 4.15). The outbound document definition is specified here. If the outbound definition and the inbound definition are not identical, then a mapping must be made between the two schemas. The “Map inbound document to outbound document” check box selects this, and the “Map reference” text box then contains a mapping file generated by the BizTalk Mapper. Finally, a digital signature can be applied to the outbound document here from a certificate store. This information informs the channel how to parse and treat the inbound document.

Figure 4.15 Configuring the Channel’s Outbound Document Type

Next, the wizard accepts logging configuration information (Figure 4.16). As mentioned in the channel filtering section, you can opt to have the inbound and/or outbound documents saved to the tracking database in either the native format, the intermediate XML format, or both.

Figure 4.16 Configuring the Channel’s Document-Level Logging Options

The final screen of the wizard (Figure 4.17) configures advanced properties of the channel, including the X.12/EDIFACT-specific group number, the number of document delivery retry attempts, and the retry interval.

Figure 4.17 Configuring Advanced Channel Properties

Note

Receipt Configuration

Receipt configuration consists of two separate tasks:

·     Requesting that a destination system send a receipt back to your organization

·     Generating and sending a receipt in response to a request by a trading partner’s system

Both of these options are configured through the Channel wizard. The first option is accommodated by the “Expect receipt” check box. When requesting a receipt with this functionality, a document definition must be present in the system to handle the returned receipt. The second option requires a receipt channel/messaging port combination to be set up and referenced by the current channel in order for return receipts to be generated by your BizTalk Server. The internals of receipt processing are covered in detail in Chapter 6, “Tracking and Receipts.”

Ports

While channels are used to configure a document’s source and its subsequent processing, BizTalk messaging ports represent the configuration of a document’s destination. Messaging ports allow you to specify the types of configuration important in packaging, securing, and transporting your document to its destination organization or application.

Static and Dynamic

Much like channels, messaging ports can be configured either to target a specific organization or application as the destination, or to specify an “open destination.” Statically defined messaging ports specifically define the destination organization (or application) and the appropriate organization identifier for that organization. This enables BizTalk Messaging to directly include that transport information in the BizTalk envelope header. In some cases, however, you might not know exactly where your document should be sent immediately upon its arrival in the messaging port. In these situations, you would choose to make this an “open” or “dynamic” messaging port.

In open messaging ports, the document’s destination must be specified in the document itself. The easiest way to accomplish this is to create a document specification that itself denotes the destination type and value, and then have your channel validate the document instance against that specification. An example of setting the destination routing parameters is shown in Figure 4.18.

Figure 4.18 Specifying Document Routing Information within BizTalk Editor

In this example, a simple document structure was created that contains a “Routing” node. This node contains DestinationType (corresponding to the organization identifier type) and DestinationValue (the organization identifier value) fields. In Figure 4.18, the right pane on the Dictionary tab shows that beside the Destination Type and Value properties are XPath expressions describing where to find these values in the instance document. These XPath expressions are packaged into the document specification and subsequently packaged with the BizTalk envelope during transit so that the receiving messaging port can identify the transport information dynamically and apply the appropriate routing to the document.

Using the Messaging Port Wizard

The first step in creating a messaging port is to decide whether the destination will be another organization or an application. Just as channels can accept documents submitted from a trading partner or a home application (but not specifically from remote applications or the generic home organization), a messaging port must send its document to a trading partner or a home application. This choice must be made initially before the wizard will appear, by choosing File | New | Messaging Port and then choosing either To an organization or To an application. After this step, the Messaging Port wizard appears.

The first screen of the wizard (Figure 4.19) looks a lot like that of the Channel wizard, asking for a messaging port name and some friendly comments.

Figure 4.19 Creating a New Messaging Port

The second screen provides information on the document’s destination, and its appearance depends on whether you chose the destination to be an application or an organization. Let’s look at the organization situation first (shown in Figure 4.20). The option is provided for you to choose between an “open destination” and a trading partner organization, as explained earlier. This example chooses an organization called “Destination, Inc.” and subsequently identifies its primary transport as an HTTP URL. BizTalk Messaging allows messaging ports to choose one of several transport options, including HTTP, HTTPS, a file, a message queue, SMTP, and a custom application integration component. The target (a URL in this case) is specified along with the transport mechanism here. If, on the other hand, the destination is chosen as an application, the second screen looks like that in Figure 4.21. Instead of prompting for an open destination or organization, this screen gives you the option of choosing a new or running XLANG schedule (XLANG schedules are discussed further in Chapter 7, “BizTalk Orchestration Services”) or an application of the home organization. In this example, an application was chosen. The same transport options are present for both application and organization document destinations.

Figure 4.20 Configuring a Port for a Destination Organization

Figure 4.21 Configuring a Port for a Destination Application

Figure 4.22 shows the next screen, which allows you to specify envelope information. Envelope information must be supplied if you must be able to handle outbound documents in a custom format. If you do not specify any envelope here, the document will be sent in XML format.

Figure 4.22 Configuring the Messaging Port Envelope

The final screen of the Messaging Port wizard enables you to specify security information as shown in Figure 4.23. MIME encoding and S/MIME encryption can be specified at this step. In addition, a digital signature can be applied in order to help your destination verify that the document has not been altered during transit. Finally, you’re given the option to create a new channel based on this port. Since channels are inexorably attached to messaging ports, this option provides you with a convenient way to jump from messaging port configuration straight into configuring a channel that uses the port.

Note

Figure 4.23 Configuring Messaging Port Security

Distribution Lists

A distribution list is a simple way to associate multiple messaging ports for delivery of documents to each member of a list of trading partners. Distribution lists can be created from the Messaging Manager interface by choosing File | New | Distribution list. The New Distribution List interface is shown in Figure 4.24. It simply allows you to select from a list of all messaging ports on the left, and add the ports of interest to the list on the right. Distribution lists can be used just as messaging ports, in that a channel can be configured to use a distribution list as its document destination. The result is that an identical document is sent to each member of the list.

Figure 4.24 Creating a Distribution List

Debugging…

Using Receive Functions

Receive functions can provide an excellent tool to obtain a “snapshot” of your document transfer process through BizTalk Messaging. If you configure your messaging ports to save your documents to the file system rather than to an orchestration schedule or an HTTP resource, you will find it easier to examine those files as they are produced. If you have a more complex pipeline that your documents must traverse, you can use this technique to examine each step of the process. Use file receive functions to send documents to your channels, and then configure your ports to output your resulting documents to the file system. By building these units end-to-end and selectively disabling the receive functions from their property pages, you can examine a document’s status at any point in the pipeline.

Messaging Services Object Model

The BizTalk Messaging Services object model is a full-featured interface to the capabilities of BizTalk Messaging, with capabilities surpassing even what is possible to do from the Messaging Manager interface. BizTalk exposes this functionality via a COM type library called the “Microsoft BizTalk Server Configuration Objects 1.0 Type Library,” which enables you to use this object model from any COM-aware development language. In order to use this functionality from within Visual Basic, for example, simply set a project reference to the type library as shown in Figure 4.25

Figure 4.25 Adding a Project Reference to the BizTalk Configuration Objects

After the reference is created, you can access any of the interfaces shown in Figure 4.26.

Figure 4.26 The BizTalk Messaging Object Model

Although the interface names begin with “I” (“IBizTalkConfig” for example), when accessing them through Visual Basic, you’ll directly access classes without the “I prefix (such as “BizTalkConfig”). The methods and properties of all these objects are too numerous to mention here, but are documented in the BizTalk Server 2000 documentation.

Any code written to use this object model must begin with the BizTalkConfig object. This object serves as the “parent” to all of the object collections that are stored in the configuration database, such as channels, ports, organizations, and so forth. BizTalkConfig objects have several properties—as shown in Figure 4.26—each of which represents one of these collections of messaging objects. In contrast to many object models that you might be familiar with in Visual Basic, these “collection” objects are not really Visual Basic collections at all. Rather, they are ADO Recordset objects, and must be accessed as such. This occasionally proves to be an awkward way to access the members of the collection, but it works. Depending on the specific type of object in the collection, the ADO Recordset contains different fields. For example, in the BizTalkConfig.Ports Recordset, you’ll find “ID” (although the documentation will tell you “Handle”), “Name,” and “DateModified.” In a pattern common to all of these recordset/collections, in order to access an individual object represented by a row in the recordset, you must first obtain the ID of the object. Once you have the ID in hand, you can create an instance of the object by calling the BizTalkConfig.CreateXXX() method, where XXX is one of Channel, Document, Envelope, Organization, Port, or PortGroup. These methods return an “empty” object of the appropriate type. The empty object shell can be populated with a real object from the system by calling its “Load” method, passing in the ID from the recordset. The following Visual Basic code demonstrates how to use this technique to obtain information on the messaging ports configured on the BizTalk Server.

 

Dim config As BTSObjectModelLib.BizTalkConfig

Dim rs As ADODB.Recordset

Dim port As BTSObjectModelLib.BizTalkPort

 

'Get a reference to a config object, the starting

'point to accessing all other BizTalk objects

Set config = New BizTalkConfig

 

'Get a list of configured ports

Set rs = config.Ports

 

'Loop through the recordset list of ports

Do While Not rs.EOF

 

    'Create a new "empty" port object

    Set port = config.CreatePort()

 

    'Load the port object with "real" data

    'based on the "id" handle in the recordset

    port.Load CLng(rs("id").Value)

 

    'Do useful work with the port... here we

    'merely print out some properties

    Debug.Print "Port name: " & port.Name

    Debug.Print "Port comments: " & port.Comments

 

    'Go to the next port in the list

    rs.MoveNext

Loop

This code simply creates a BizTalkConfig object, and then loops through the recordset obtained from its “Ports” property. For each row in the recordset, it creates an empty BizTalkPort object, and then loads the correct object from the database based on its ID handle. In this sample, we simply print the name and comments fields for each messaging port.

Not only can you merely read existing messaging configuration with this functionality, you can also create new messaging objects. The following Visual Basic code builds up a document path through BizTalk Server, first creating both source and destination organizations, then creating a document definition, and finally creating and configuring the messaging port and channel for the document exchange.

 

'Get a config object

Dim config As BTSObjectModelLib.BizTalkConfig

Set config = New BizTalkConfig

 

'Create a new source and destination organization

Dim org As BizTalkOrganization

 

'Get an empty organization

Set org = config.CreateOrganization

 

'Set its properties

org.Name = "Sad Clown Enterprises"

org.Comments = "Sad Clown is a sample source organization"

 

'Persist it to the configuration database

org.Create

Dim sadClownHandle As Long

sadClownHandle = org.Handle

First, we again acquire a BizTalkConfig object. We’ll use this object repeatedly to create our helper objects along the way. Next, we create our source organization with the “CreateOrganization” method. We then set the properties, and then call “Create” on the organization object. “Create” causes the current data in the new object to be persisted to the configuration database. Similar steps are then taken to create a destination organization.

'Duplicate these steps for a new destination organization

Set org = config.CreateOrganization

org.Name = "Happy Clam, Inc."

org.Comments = "Happy Clam is a sample destination org"

org.Create

Dim happyClamHandle As Long

happyClamHandle = org.Handle

 

 

'Create a new document definition

Dim doc As BizTalkDocument

Set doc = config.CreateDocument

doc.Name = "Sad Clown Invoice"

doc.Reference = "http://CHRISF/BizTalkServerRepository/" & _

        "DocSpecs/Microsoft/CommonInvoice.xml"

doc.Create

A document definition is then created, referencing a file in the WebDAV repository, and persisted to the configuration database.

'Create a messaging port

Dim port As BizTalkPort

Set port = config.CreatePort

port.Name = "Port to Happy Clam"

 

'Set the port's endpoint information

Dim endpoint As BizTalkEndpoint

Set endpoint = port.DestinationEndpoint

endpoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

endpoint.Organization = happyClamHandle

 

'Set the port's transport information

Dim trans As BizTalkTransportInfo

Set trans = port.PrimaryTransport

trans.Type = BIZTALK_TRANSPORT_TYPE_HTTP

trans.Address = "http://www.happyclaminc.com/documents"

 

'Persist the port

port.Create

 

Next, the messaging port is created and configured. Note the two helper objects here of type BizTalkEndpoint and BizTalkTransportInfo. When you create a new BizTalkPort object, it is created with default representations of these objects as properties. These must be configured with the port itself in order to completely specify the port’s properties. In our example, we specify that the destination is not open and that the document destination endpoint is the Happy Clam organization whose handle we stashed away earlier when creating the organizations. Similarly, we configured the transport to occur over HTTP, and we specified the destination URL to that endpoint. Finally, we persist the port to the database.

 

'Create a channel

Dim channel As BizTalkChannel

Set channel = config.CreateChannel

'Set the channel's name and documents

channel.Name = "Sad Clown Channel"

channel.InputDocument = doc.Handle

channel.OutputDocument = doc.Handle

 

'Point to the port we just created

channel.port = port.Handle

 

'Set the channel's source organization

Set endpoint = channel.SourceEndpoint

endpoint.Organization = sadClownHandle

endpoint.Openness = BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

 

'Persist the channel

channel.Create

Finally, we create the channel that uses all of the previous objects. We configure the input and output documents, passing our document’s handle to the channel properties. (If these documents had been different, a document mapping can be specified from the channel object.) We also set the destination port to that which we just created. Similar to the previous port example, we then set the source endpoint for the channel to point to our Sad Clown source organization. We end by saving the channel to the database.

Developing & Deploying…

Replicating Configuration Data

In many cases, you will be developing your applications on a development server, while your application will be targeted at a production server. Be careful about using the Messaging Manager to set up and configure a live BizTalk system. While the Messaging Manager provides a clear and consistent interface, the many steps that are required to fully configure each object leave the door wide open to introducing bugs. Instead, look into using the BizTalk Server Configuration Assistant application (Figure 4.27). This is an officially unsupported application that is included with BizTalk Server 2000 and is located in the C:\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\BTConfigAssistant\EXE directory. Source code is also available for this application, which will give you a head start on using the many features of the BizTalk messaging object model.

Figure 4.27 The BizTalk Configuration Assistant

 

Summary

BizTalk Messaging Services is (along with BizTalk Orchestration) a core feature of BizTalk Server. Messaging Services represents the objects that participate in your business flow, and allow you to configure them through the BizTalk Messaging Manager. These objects are organizations, document definitions, document specifications, organizations, channels, messaging ports, and distribution lists. Organizations represent the logical endpoints—both source and destination—of the document exchange. Document definitions reference a specific document type and provide the ability to track and persist specific document fields to a database. Document specifications represent the schema/layout of the instance document, as well as specify any document routing information and any other transport-specific parameters that reside in the message envelope. Channels represent the document source. As the document is submitted to BizTalk Server, an appropriate channel will accept the document based on its configured source organization and/or document definition. Messaging ports represent the document destination, and must accept documents from channels, package them, and deliver the documents to the destination organization. Finally, distribution lists serve as convenient collections of messaging ports, allowing a channel to route its documents to multiple recipients at once.

In addition to its fundamental objects, BizTalk Messaging Services also specifies the path that a document must take through BizTalk Server. In summary, when a document is submitted to BizTalk Server, a channel picks up the document after recognizing it was sent from a particular source organization, then validates the document against a document definition/specification. The channel and/or the document definition can optionally save document tracking data to the tracking database. The channel then processes and/or transforms the document (based on a specified map between differing input and output document specifications) before passing it to an associated messaging port or distribution list. The messaging port then packages and optionally signs, encodes, and encrypts the document before sending it to the destination.

BizTalk Messaging can be configured via the BizTalk Messaging Manager application or a COM object model. The BizTalk Messaging object model contains classes representing each of the objects that are configurable from the Messaging Manager. The BizTalkConfig object represents the high-level parent and contains ADO recordset collections of Channels, Ports, Organizations, Documents, and PortGroups (distribution lists). The BizTalkConfig class also contains methods that create empty shell objects (e.g., CreatePort() ), from which new messaging objects can be created and subsequently persisted to the configuration database.

Solutions Fast Track

BizTalk Messaging Services

·     BizTalk Messaging Services is a core feature of BizTalk Server.

·     Messaging Services is responsible for packaging and routing documents from source to destination.

·     Messaging Services is configurable via the BizTalk Messaging Manager application and through a COM object model.

Document Definitions

·     Document definitions represent a specific type of document that can arrive at your BizTalk Server.

·     Global tracking fields can be defined that allow specific data from your instance documents to be persisted to the tracking database.

·     You should always choose a document specification when creating a document definition—without it, you will see reduced functionality.

Specifications

·     Specifications represent the schema of the instance documents and specify how to interpret non-XML instance documents.

·     One can create specifications easily with the BizTalk Editor application.

·     Mapping can be performed between different specifications using the BizTalk Mapper.

Organizations

·     An organization represents your home organization as well as your trading partners with whom you exchange documents.

·     Only a home (default) organization can be associated with applications.

·     An organization can have any number of unique organization identifiers as long as the identifier’s value uniquely describes a single organization.

Channels

·     Channels serve as the “source” of document routing through BizTalk Server.

·     Channels can be configured as a receipt channel, specifying that the channel is intended to send a document receipt to a trading partner.

·     Channels can be configured to filter documents or track document fields based on XPath expressions.

Ports

·     Ports serve as the “destination” of document routing through BizTalk Server.

·     Ports receive documents from a channel, and then package, secure, sign, and deliver to the destination.

·     Ports must be created before any associated channels.

Distribution Lists

·     Distribution lists serve as lists of messaging ports.

·     A channel can specify a distribution list as a target document destination to route the document to each of the list’s members.

Messaging Services Object Model

·     All messaging configuration objects can be accessed through methods and properties of the BizTalkConfig parent object.

·     The BizTalkConfig object’s “collection” properties are not really collections at all—they are ADO recordsets.

·     The BizTalkConfig object can create an empty object shell with the CreateXXX methods (CreatePort, for example), while the Create method on the object itself will persist the object to the configuration database.

Frequently Asked Questions

Q: How can I create a document specification for a flat-file format?

A: Use the BizTalk Editor, just as if you were building a specification for an XML-based document. Build the desired hierarchy, and then change the root node’s “Standard” property value to CUSTOM. Finally, specify the appropriate record and field delimiters and element cardinality. You can validate your specification against an instance document using the Tools | Validate instance menu option.

Q: How can I obtain a reference to a channel from the messaging object model?

A: First, create an object of type BizTalkConfig. From there, use its Channels property to obtain an ADO recordset containing one row for each channel on the server. Determine a record’s value for the “ID” field to retrieve a “handle” to the individual channel. Obtain an empty “shell” channel using the BizTalkConfig’s “CreateChannel” method, and then call that BizTalkChannel object’s “Load” method, passing in the handle to the channel of interest. Your channel will now be populated with information from the configuration database.

Q: How can I narrow down the types of documents that a channel receives?

A: Each channel can specify a channel filter. This filter is based on the channel’s document definition, and consists of various XPath expressions. If the expressions evaluate to true, then the document is accepted into the channel.

 

<< Go back to Page 1