FIX: The tracking event stream is not exposed in BizTalk Server 2004 orchestrations

In Microsoft BizTalk Server 2004, the tracking event stream is not exposed in orchestrations. Therefore, orchestrations that use the Business Activity Monitoring (BAM) API cannot access the tracking event stream.

Without access to this tracking event stream, BAM events that are generated by an orchestration are not transactionally consistent with the orchestration state. In this scenario, you may experience one of the following symptoms:

�	You lose some BAM events data.
�	You have an inaccurate association between the orchestration state and the BAM events.

To resolve this problem, a new callable class has been created to allow for access to the BAM streams.

Hotfix information

A supported hotfix is now available from Microsoft. However, this hotfix is intended to correct only the problem that is described in this article. Apply this hotfix only to systems that are experiencing this specific problem. This hotfix might receive additional testing. Therefore, if you are not severely affected by this problem, we recommend that you wait for the next service pack that contains this hotfix.

To resolve this problem, submit a request to Microsoft Online Customer Services to obtain the hotfix. To submit an online request to obtain the hotfix, visit the following Microsoft Web site:Note If additional issues occur or any troubleshooting is required, you might have to create a separate service request. The usual support costs will apply to additional support questions and issues that do not qualify for this specific hotfix. To create a separate service request, visit the following Microsoft Web site:
Warning You cannot roll back this hotfix from the BizTalk Server environment. Therefore, make sure that you fully test this hotfix in a test environment before you apply this hotfix to a production environment. Do not try to use Add or Remove Programs to remove this hotfix because this does not roll back the database changes, and leaves the BizTalk Server environment in an inconsistent state.

Prerequisites

No prerequisites are required.

Restart requirement

You do not have to restart the computer after you apply this hotfix.

Hotfix replacement information

This hotfix does not replace any other hotfixes.

File information

The English version of this hotfix has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time tool in Control Panel.

   Date         Time   Version     Size     File name
   -----------------------------------------------------------------------------------
   19-May-2005  19:23               10,620  Bameventbusmgmt_schema.sql
   23-May-2005  22:29  3.0.6127.0   57,344  Microsoft.biztalk.bam.eventobservation.dll
   24-May-2005  02:00  3.0.6128.0    9,216  Microsoft.biztalk.bam.xlangs.dll
   27-May-2005  22:48  3.0.6129.0  221,184  Microsoft.xlangs.biztalk.engine.dll
   23-May-2005  22:42  3.0.6127.0  221,184  Microsoft.xlangs.engine.dll
   23-May-2005  22:29  3.0.6127.0  114,688  Microsoft.xlangs.runtimetypes.dll
   19-May-2005  19:23                6,606  Msgbox_tracking_logic.sql

Note Because of file dependencies, the most recent hotfix that contains these files may also contain additional files.

Microsoft has confirmed that this is a problem in the Microsoft products that are listed in the "Applies to" section.

After you install this hotfix, the following methods are added to the Microsoft.BizTalk.Bam.XLANGs assembly:

�	AddRelatedActivity
�	BeginActivity
�	Clear
�	EnableContinuation
�	EndActivity
�	UpdateActivity
�	StoreCustomEvent

The AddRelatedActivity method

This method declares another activity instance that is related to the current activity instance.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.AddRelatedActivity(System.String,System.String,System.String,System.String)
�	Parameters: � activityName This parameter is the current activity name. � activityID This parameter is the current activity instance ID. � relatedActivityName This parameter is the related activity name. � relatedTraceID This parameter is the related activity instance ID.

When you call the AddRelatedActivity method, a reference to the related activity instance is stored together with the activity data. For example, a reference to the corresponding "Shipment Batch" may be stored in a "Purchase Order" activity instance.

Use the AddRelatedActivity method when the following conditions are true:

�	You want to match additional data.
�	The additional data represents another activity that is exposed through BAM.

Use the Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EnableContinuation(System.String,System.String,System.String) method when the following conditions are true:

�	You only want to match your data to additional activity data that exists in a different part of your application.
�	The different part of your application does not have the original ActivityID.

In this situation, the data is stored in the same activity record.

The BeginActivity method

This method creates a new activity record if data is tracked by using the Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.UpdateActivity(System.String,System.String,System.Object[]) method.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity(System.String,System.String)
�	Parameters: � activityName This parameter is the name of the activity. � activityInstance This parameter is the activity instance ID.

A new activity record is hidden until the BeginActivity step is processed. Do not call the BeginActivity method when the data is tracked in the context of activity continuation. You can use this method to hide out-of-order event data. This method helps prevent data aggregation and analysis problems. A visible record is not created until the BeginActivity track point is reached.

The Clear method

This method clears the buffered data.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.Clear

The EnableContinuation method

This method enables data that is tracked in a different context to contribute to a particular activity record.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EnableContinuation(System.String,System.String,System.String)
�	Parameters: � activityName This parameter is the activity name. � activityInstance This parameter is the activity instance ID or the continuation token. � continuationToken The continuation token is used to send additional data to the activity record.

You must use the EnableContinuation method when the application contains multiple components and when one of the following conditions is true:

�

The original ActivityID is not propagated to some components. For example, a "PurchaseOrder" activity that is named "PO#123" raises the Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EnableContinuation(System.String,System.String,System.String) method to "UPS#5749". In this example, all the calls to the UpdateActivity("PurchaseOrder", "UPS#5749", "", ...) method add data to the original activity record ("PurchaseOrder", "PO#123") instead of creating a new record. When this behavior occurs, you do not have to propagate the original ActivityID to all components to match the events. Instead, a different component of the application can use a different ActivityID.

�

The components of the application asynchronously send events to BAM. For example, the application components send events to BAM by using different instances of the Microsoft.BizTalk.Bam.EventObservation.BufferedEventStream class. This behavior is a problem because the asynchronous event data may be processed out of order. Therefore, you may receive incorrect results, such as "150 percent of the Purchase Orders are Delivered." This behavior may occur if the "Delivered" data is processed one second before the "Received" data. The BAM infrastructure prevents this behavior by temporarily hiding the asynchronous event data from continuations if this event data is received out of order. Note If this condition is true, you must use the EnableContinuation method, even if all the components have the ActivityID set. In this scenario, the continuation token must be distinct from the ActivityID. For example, you can make the continuation token distinct by adding a unique prefix. After some components of the application call the EnableContinuation method, other components may raise additional events by using the UpdateActivity method together with the continuation token instead of using the ActivityID. After this process is finished, each component must call the EndActivity method together with the continuation token to inform the BAM infrastructure that no additional events are expected.

The EndActivity method

This method indicates that no more events are expected for the specified activity instance or continuation token.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EndActivity(System.String,System.String)
�	Parameters: � activityName This parameter is the activity name. � activityInstance This parameter is the activity instance ID or the continuation token.

The UpdateActivity method

This method updates the activity record.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.UpdateActivity(System.String,System.String,System.Object[])
�	Parameters: � activityName This parameter is the activity name. � activityInstance This parameter is the activity instance ID or the continuation token. � All data items that must be updated as name-value pairs

All updates to the specified activity instance must occur before the Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EndActivity(System.String,System.String) track point.

The StoreCustomEvent method

This method stores custom events, such as DelayedSpCall objects.

�	Method name: Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.StoreCustomEvent(Microsoft.BizTalk.Bam.EventObservation.IPersistQueryable)
�	Parameter: � singleEvent This parameter is the Event class instance.

For more information, click the following article number to view the article in the Microsoft Knowledge Base: