BAM API: Using OrchestrationEventStream

Since there is not much documentation* on this yet on how to use OrchestrationEventStream (an EventStream that is in synch with Orchestration), here is a quick info on the howto:

This new feature is found in Microsoft.BizTalk.Bam.XLANGs assembly.  From you BizTalk project, you can write the following in your orchestration, e.g. Expression Editor (click on the appropriate shape in orchestration to launch this):

// Sample code for using OrchestrationEventStream from an orchestration, no need to new it:
Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity( "PurchaseOrder", "PO123");

Note: this only applies to Biztalk 2006.

* To use this in Biztalk 2004 SP1, you will need a hot fix, its kb article can be found here:,


Comments (12)
  1. Eric Stott says:

    So does this use the UpdateActivity? Also, when does this actually get sent to the MessageBox, (it goes to the MessageBoxDB, or does it go directly?). Also, what is the purpose of the Clear method, is it analagous to the flush? You state that you don’t need to new it, however it is available, can you tell us in what situations you would need to use it?

  2. keithlim says:

    OrchestrationEventStream is derived from EventStream, so all the other methods and properties of EventStream are available to OES.  The EventStream doc should provide you with all the informatation you need. Link:

    When you write the code in Orchestration shape itself, such as an Expression Editor, the OES as shown in the above syntax would participate in the context of the Orchestration… meaning, internally the events submitted on this static OES class would be piggy-backing on the Orchestration buffer.  

    You would use this when you want consistency between Orchestration persistence and BAM persistence… in other words, if Orchestration throws an exception before reaching the next persistent point, any BAM event written since last persistent point would not be persisted as well.

    This is in contrast to using DirectEventStream or BufferedEventStream where once you have sent the event, it would get persited regardless if the Orchestration subsequently encounters an exception.

    Of all the EventStream, only DirectEventStream goes to BAMPrimaryImport directly. All the others, BES/MES/OES will be persisted to MessageBox first.

  3. Eric Stott says:

    So then what is the context of the MES, it persists as long as the Message persists?

  4. keithlim says:

    MES (MessagingEventStream) is only available from within the pipeline (custom pipeline components) and it participates in the pipeline transaction.  Meaning, if the pipeline encounters a problem, the BAM event submitted via MES would not be persited.  This is important in cases where should the pipeline logic retry processing of a failed message, there won’t de many of the same BAM events sent.

  5. Dinesh says:

    not related to this specific topic, but what is the advantage of MES over BES? what exactly is meant by participating in pipeline transaction, thanks

  6. keithlim says:

    Hi Dinesh,

    Here are the differences between MES and BES:

    MES participates in pipeline transaction, if your pipe is suspended or having an exception and roll back, the BAM data written via MES would be consistent with the pipeline state. In these cases, there would be no BAM data written as well.

    You do not need to supply the connection string for MES, so no hardcoding.  But not only that, if you have multiple message boxes in your setup, it would not how to load balance between them.

    So, those are two advantages you get for MES over BES.


    Keith Lim [MSFT]

  7. Nick says:

    Keith, thank you for the great insight into how OrchestrationEventStream works. I have a quick question about using it: my expression shapes that deal with BAM activities do it by calling methods that are in other assemblies, and I’m not sure how scoping rules apply with OrchestrationEventStream (i.e. Is the method in the external assembly "part of" the executing orchestration?). Am I able to call OrchestrationEventStream.DoSomething() from the method in that other assembly and I will get the desired behavior of OrchestrationEventStream? Additionally, will I only need to reference Microsoft.BizTalk.Bam.XLANGs in the called assembly or will I need to reference it in the assembly that contains the orchestration as well?



  8. keithlim says:


    On your first question, I see no reason why it won’t work. I believe there was another client that tried this out.  I haven’t had time to try this out myself.  Would greatly appreciate if you try it out and share the result.

    If not I will post a result perhaps earlier next week.

  9. Nick says:

    Hi Keith,

    Sorry I didn’t get to this sooner. I tried calling OrchestrationEventStream methods from an external assembly and all seems to work fine. I’ve only done a tiny bit of ad-hoc testing, so I can’t confirm that the behavior is exactly what is expected in terms of transactional processing, but everything gets populated to the tables. Not entirely sure how it gets the executing orchestration instance through reflection since nothing about the orchestration is passed directly to my method – I imagine it’s through reflection or just calling context.

    To answer my own questions from last week, yes, calling OrchestrationEventStream methods from an external assembly works, and you only need to reference Microsoft.BizTalk.Bam.XLANGS in the assembly that is calling those methods (as opposed to having to reference it in the orchestration assembly too).


  10. keithlim says:

    Hi Nick,

    You are right on both 🙂  Under the cover it is using CallContext class, if a specific tracking data object is not found, nothing will be done.

    So, if you happen to share this code somewhere else that is not in Orchestration context, nothing will happen.



  11. Many of you guys are eagerly anticipating the release of the Microsoft BizTalk Server 2006 R2… and the

Comments are closed.

Skip to main content