Submitting Documents Via the IInterchange Interface

Documents targeted for BizTalk Server must be transmitted to the server in some way. The appropriate submission method depends on the architecture of the source application and the requirements of the overall business process. You may choose from any of the following delivery protocols:

• HTTP—Hypertext Transport Protocol

• HTTPS—Secure HTTP

• MSMQ—Microsoft Messaging Queue

• SMTP—Simple Mail Transfer Protocol

• File—File-based transmissions

• COM/DCOM—Direct submissions via the Component Object Model or Distributed Component Object Model

With the exception of using COM/DCOM, the preceding approaches do not directly initiate BizTalk Server processing; they simply provide a means of transportation for messages. At some point during the submission process, the IInterchange interface must be employed. IInterchange may be used “behind the scenes” by BizTalk Server (this is how receive functions work), or it may be used directly by a source application.

IInterchange provides an API for submitting documents either synchronously or asynchronously. It also contains a set of methods for administering the suspended queue in case the document is rejected by BizTalk Server for some reason. A total of five methods are in the interface:

• Submit()

• SubmitSync()

• CheckSuspendedQueue()

• GetSuspendedQueueItemDetails()

• DeleteFromSuspendedQueue()

The following sections discuss how to use the IInterchange interface to initiate BizTalk Server processing.

Synchronous Versus Asynchronous Processing

IInterchange::Submit() creates and sends an interchange to BizTalk Server for asynchronous processing. This means that after the document has been placed in the work items queue, the calling program continues to execute, without waiting for the interchange to be processed. Alternatively, IInterchange::SubmitSync() sends a document to BizTalk Server and then waits for the interchange to finish processing before executing any subsequent code. The only major difference between the two methods is the fact that the SubmitSync method has the capability to return a response in addition to the interchange handle when executed. Because this is the only difference, we will focus on the IInterchange::Submit() method for the remainder of this section.

IInterchange::Submit() Parameters

One thing that makes IInterchange::Submit() so powerful (and challenging to master) is the seemingly endless combinations of parameters that the function will accept. Listing 12.1 shows the syntax of IInterchange::Submit().

Listing 12.1. IInterchange::Submit() Syntax

HRESULT Submit(
    BIZTALK_OPENNESS_TYPE lOpenness,
    BSTR Document,
    BSTR DocName,
    BSTR SourceQualifier,
    BSTR SourceID,
    BSTR DestQualifier,
    BSTR DestID,
    BSTR ChannelName,
    BSTR FilePath,
    BSTR EnvelopeName,
    long PassThrough,
    BSTR* SubmissionHandle
);

The following sections describe each parameter and the effects it can have on message processing. You may use this section both as a reference and to establish a foundation on which to build your understanding of advanced messaging topics.

The lOpenness Parameter

The first parameter, lOpenness, indicates whether the source and destination of an interchange are explicitly specified or open. The value of the lOpenness parameter must belong to the BIZTALK_OPENNESS_TYPE enumeration, which is documented in Table 12.1.

The value of lOpenness dictates whether messaging ports associated with an interchange can be configured as open. Open ports are discussed later in this chapter.

The lOpenness parameter also has implications on whether EDI formats are allowed in an interchange. If BIZTALK_OPENNESS_TYPE_SOURCE is used with an inbound EDI document, then the outbound document format cannot be EDI. If BIZTALK_OPENNESS_TYPE_ DESTINATION is used, then the inbound document format cannot be EDI.

Identifying the Document Being Submitted

A document submitted to BizTalk Server for processing can be specified using the Document parameter or the FilePath parameter. If the Document parameter is used, you are expected to pass the pure bytes of the inbound document file. You cannot pass object pointers such as an XML DOM object or an ADO object using this parameter. If you specify a value for the Document parameter, then you cannot pass a value for FilePath parameter.

FilePath offers an alternative to submitting the document as a pure string. Using this parameter, you specify the path to the disk file that contains the document. The path value must be either a Uniform Resource Locator (URL), Universal Naming Convention (UNC) path, or a drive letter and disk path combination. URL and UNC formats eliminate the need to maintain a permanent network drive mapping on the BizTalk Servers if the input file resides on a remote machine.

Using the FilePath parameter may result in a slight performance penalty if the file resides on a remote machine because the document must be located and copied to the work items queue by BizTalk Server before control is returned to the calling program.

Identifying the Document Source and Destination

The document's source and destination are each specified via a pair of parameters that consist of a qualifier and an identifier. Listing 12.2 shows these parameters.

Listing 12.2. Parameters for the Message Source and Destination

BSTR SourceQualifier,
BSTR SourceID,
BSTR DestQualifier,
BSTR DestID

The SourceQualifier indicates how the SourceID parameter is to be interpreted. Valid values come from the organization identifier qualifiers created when the user creates an alias for an organization. Qualifiers are entered in the BizTalk Messaging Manager with each organization identifier and allow you to specify as many unique identifiers for an organization as you want. Common qualifiers include the Data Universal Numbering System (DUNS) number, telephone number, and BizTalk. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. The SourceID contains the value of the qualifier of the source organization. For example, if the SourceQualifier parameter is Telephone, this value is the telephone number. If the Openness flag is set to OpenSrc, SourceID is interpreted as the source organization name. The SourceID parameter cannot be used if the PassThrough parameter is set to TRUE.

In the BizTalk Messaging Manager, you cannot save an organization identifier without entering a qualifier value. However, when using IInterchange::Submit(), you can specify an organization identifier and omit the qualifier. In this case, a default qualifier value of OrganizationName is automatically assumed by BizTalk Server.

Source and destination identifier/qualifier pairs have additional constraints when transmitting EDI data. When using the X12 format, the organization qualifier must be 2 characters or less, and the identifier itself must not exceed 15 characters. When using the EDIFACT format, the qualifier must be 4 characters or less, and the identifier value must be 35 characters or less. Both X12 and EDIFACT formats do not allow the word “Organization” to be used as an identifier value.

You can omit the source organization and/or destination organization parameters completely from an IInterchange::Submit() call. In this case, BizTalk Server will attempt to determine this information by other means. This process—referred to as dynamic routing—is covered extensively later in this chapter.

Identifying the Document Format, DocName, EnvelopeName Parameters

The DocName and EnvelopeName parameters of IInterchange::Submit() enable BizTalk Server to understand the format of the documents being submitted. DocName refers to a document definition that has been configured in the BizTalk Messaging Manager. In most cases, a document definition points to an underlying BizTalk document specification, which defines the type and structure of a document. Under some circumstances, a document definition may not refer to an underlying document specification. In this case, the document submitted is not parsed or verified against a BizTalk specification, limiting the processing that can occur on the data. For example, you may want to transport a binary file, in which case you would want to pass a document through by setting the PassThrough parameter on the Submit method to True.

Envelopes are required when a non-XML message is being submitted to BizTalk Server. You can specify the envelope associated with a message by using the EnvelopeName parameter of IInterchange::Submit(). The name specified must match an envelope name that has been configured in BizTalk Messaging. Envelopes serve as a wrapper for business documents and describe the type of document being transmitted. Therefore, envelopes must point to a valid BizTalk specification configured in the Messaging system. Because many interchanges do not require envelopes, the EnvelopeName parameter is optional.

Specifying a Channel

IInterchange::Submit() allows you to explicitly specify the channel to use when processing a message. The ChannelName accepts a string value representing the name of a channel that has been configured in BizTalk Messaging. The technique of explicitly specifying a channel is one way to streamline the processing of a message because it allows BizTalk Server to bypass the “normal” channel selection process. The ChannelName param-eter is optional unless the PassThrough parameter is set to True, in which case it is required.

For more information on how BizTalk Server decides what channel to invoke, see the section “The Channel Selection Process” later in this chapter.

Pass-Through Interchange Processing

As part of “standard” interchange processing, BizTalk Server can perform encoding, encryption, and digital signature verification on a document. There are times when you may want skip these processing steps and just have BizTalk Server Messaging route a document “as is” to its destination. This is the purpose of the PassThrough parameter in IInterchange::Submit(). Setting this parameter value to True adds protection against data corruption when you are submitting binary data that must be delivered exactly as it was submitted. By skipping the encoding process, for example, you ensure that BizTalk Server does not attempt to convert the input data to a unicode character set. Delivering binary images to a trading partner is one scenario where pass-through processing might be useful.

A value of True for the PassThrough parameter also imposes some rigid constraints on the other IInterchange::Submit() parameter values. You must specify BIZTALK_OPENNESS_TYPE_NOTOPEN for the lOpenness parameter, and you must pass a value in the ChannelName parameter. The specified channel is not permitted to apply mappings on the original input data. When you specify pass-through processing, you also must omit the DocName, SourceQualifier, SourceID, DestQualifier, DestID, and FilePath parameters. The delivery location for pass-through interchange data is confined to the address configured in the channel's associated port.

Information Returned by IInterchange::Submit()

When making asynchronous function calls, there is always the question of how to track the progress of the function invoked. The calling program will continue to execute, but at some point the caller may need to know whether the asynchronous process completed successfully. IInterchange::Submit() solves this issue by returning a “receipt” to the caller in the form of a submission handle. Armed with the submission handle, the calling program can query for the status of the interchange by presenting the handle to one of several BizTalk Server API functions. The submission handle uniquely identifies the interchange invoked as a result of an IInterchange::Submit() call. Listing 12.3 displays an example.

Listing 12.3. Using the Submission Handle

Dim oInterchange As BTSInterchangeLib.Interchange
    Dim strRetVal As String
    Dim vSrcName as Variant
    Dim vDestName as Variant
    Dim vDocName as Variant
    Dim vReasonCode As Variant
    Dim vXMLDoc As Variant

        Set oInterchange = New BTSInterchangeLib.Interchange

        ' IInterchange::Submit() call
    'strRetVal contains the value of the submission handle that we will use to query  with
        strRetVal = oInterchange.Submit(BIZTALK_OPENNESS_TYPE_NOTOPEN, _
            "", _
            "", _
            "", _
            "", _
            "", _
            "", _
            "PO_GCC-KF, _
            "C:RouteTestRuntimeSourceInst_PO_KnotFree_1.xml", _
            "", _
            0, )

    ' somewhere else in your code, you could check in the suspended queue to see
    ' if the item was in the suspended queue or the reason that the item was placed in
    ' the suspended queue
    ' If this item is not in the suspended queue, vReasonCode will be Null
     oInterchange.GetSuspendedQueueItemDetails _
        strRetVal, _
        vSrcName, _
        vDestName, _
        vDocName, _
        vReasonCode, _
        vXMLDoc


    ' For a list of 'reasons' why the document might fail, see the BizTalk server
' online help 'CISReasonToQueue'
    If vReasonCode <> 0 Then
        MsgBox "Failure in submission. Reason code: " & vReasonCode
    End If


    Set oInterchange = Nothing

Submitting Messages from Remote Machines

IInterchange::Submit() allows application servers to initiate an interchange and then continue processing requests. To maximize the processing load that an application server needs to handle, it makes sense to have the capability to separate application servers from a BizTalk Server machine allowing the calling program to run on a different computer from the actual BizTalk Server(s).

To allow interchanges to be submitted from remote machines, you must create a Microsoft Installer Package (.msi file) on one of the BizTalk Server machines and run this installation package on all remote machines that will submit interchanges. To create the installation package, log in to the BizTalk Server machine directly and open the Microsoft Management Console snap-in for administering COM+ Services. A COM+ application named BizTalk Server Interchange Application should already be configured on the machine. Figure 12.1 shows the COM+ Services MMC.

Select the application in the Explorer, right-click, and choose Export. This launches the COM+ Application Export Wizard. Clicking the Next button leads to the Application Export Information dialog box shown in Figure 12.2. Enter the path for the .msi file to be created and select the Application Proxy radio button.

Clicking the Next button on the Application Export Information dialog causes the installation files to be created at the location specified. The final screen of the wizard simply informs you that the export was successful. Click the Finish button to close the wizard.

After you successfully run the export wizard, you should see two files in the designated directory—an .msi file and a .cab file. Copy these files to the target machine(s) and run the installation program.

You may need to configure the COM+ identity of the BizTalk Server Interchange Application to successfully submit interchanges when there is no interactive user on the machine. To accomplish this, right-click on the BizTalk Server Interchange Application and choose Properties. Click on the Advanced Tab, and make sure that Disable Changes is unchecked. Finally, click on the Identity tab, select This User, and enter the credentials for the appropriate user account.

Administering the Suspended Queue

The Suspended queue contains work items that have failed processing for a variety of reasons, including parsing errors, serialization errors, failed transmissions, or the inability to find a channel configuration. You can retrieve or delete items from the queue using the Interchange interface.

To retrieve items from the suspended queue, you call the CheckSuspendedQueue method of the IInterchange interface. CheckSuspendedQueue retrieves a list of items in the suspended queue that meet the search criteria specified by the parameters of the method. This returns a list of handles that can subsequently be used to call the DeleteFromSuspendedQueue or the GetSuspendedQueueItemDetails method of the IInterchange interface. To process these items, you must get the item details associated with each item in the suspended queue by using GetSuspendedQueueItemDetails. GetSuspendedQueueItemDetails retrieves the details about an item in the suspended queue.

To remove items from the suspended queue, applications call DeleteFromSuspendedQueue. DeleteFromSuspendedQueue removes from the suspended queue a list of items that meet the search criteria specified by the parameters of the method.

One note of interest, the sixth parameter of the GetSuspendedQueueItemDetails() method contains the actual XML document passed into the suspended queue. If you retrieve this XML document, it is possible with a little programming expertise, to be able to programmatically resubmit this XML document to BizTalk and then delete the item from the suspended queue.