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 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 software update that contains this hotfix.
If the hotfix is available for download, there is a "Hotfix download available" section at the top of this Knowledge Base article. If this section does not appear, contact Microsoft Customer Service and Support to obtain the hotfix.
Note If additional issues occur or if 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. For a complete list of Microsoft Customer Service and Support telephone numbers or to create a separate service request, visit the following Microsoft Web site:
Note The "Hotfix download available" form displays the languages for which the hotfix is available. If you do not see your language, it is because a hotfix is not available for that language.
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
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:
824684Â
(http://kbalertz.com/Feedback.aspx?kbNumber=824684/
)
Description of the standard terminology that is used to describe Microsoft software updates