After focussing my orchestration efforts on the tools by the folks at OpenStorm, I started exploring the orchestration capabilities of BizTalk Server 2004. The standards focused approach of the OpenStorm tools is very appealing, but BizTalk's rich feature set and the integration of .NET into orchestrations allow to build very powerful orchestrations without having to develop services for everything that's not covered by the BPEL standard.

The lack of BizTalk developer documentation however, is making it very hard to take your first baby steps with BizTalk. You feel like a toddler with the urge to run, but you first have to master taking simple steps first. I had quite a few moments where I just wanted to plop on my butt an cry until my mommy comes and makes it all go away ...

I hope this article will help some people to get past the baby step phase quicker and get them running in no time.

Installation

The BizTalk installer does not take care of installing all the prerequisites. Here are two issues I ran into. Although both issues are documented in the Microsoft Knowledgebase, the installation does not install these items if they are not already present on your computer.

• The BizTalk installer does not take care of installing all the prerequisites. For example, the Health and Activity Tracking (HAT) tool requires of the Office XP version of the Web Controls. If you don’t have the OWC10.dll installed and registered you will get the following error when you run the HAT: 'Activeview.columnaxis' is null or not an object.
  
  This problem and the solution are documented at: http://support.microsoft.com/?kbid=836119
• Deploying an orchestration results in an InvalidCastException without installing a COM+ hotfix.

Types

• An orchestration knows variables of 2 types: Messages and Variables. Messages correspond to XML Schema types and Variables correspond to .NET Types. You can access data in messages via properties you define with the schema editor or the xpath() function.
• Orchestration Variables must be of Xml serializable types, if their scope is beyond a scope with atomic transaction behavior. The types need to be serializable so BizTalk can persist an orchestration instance to XML when it needs to dehydrate it. This makes sense because the XmlSerializer is the about the fastest way to map between object instances and XML documents, but you need to keep in mind the limitations that the XmlSerializer imposes when you add variables to your orchestration. Unfortunately, one class that does not conform to these limitations is the XmlNodeList. Therefore you can't store a message fragment you selected you got by calling XmlDocument.SelectNodes in an orchestration variable.

Working with Message Types

• The first realization one needs to have is that any Message in an orchestration can be assigned to a Variable of the .NET type System.Xml.XmlDocument. 
• You can assign XML data from one message to another with the data mapper or the expression editor. While the data mapper is much easier to work with, it prevents BizTalk to export the orchestration to BPEL even if your maps don't use any custom functiods (bummer!). Btw: the OpenStorm orchestrator on the other hand can export graphical data maps to BPEL ...

The Expression Editor

• The Expression editor marries the two type systems (.NET and XML Schema) available to an orchestration. You can write C#-like code against .NET classes, assign parts from one message to another and execute XPath expressions against messages.
• Of course, expressions calling .NET objects do not export to BPEL ...
• You can call System.Diagnostics.*.WriteLine to generate trace and debug messages to follow the execution of an orchestration in DebugView. For simple debugging tasks trace messages can be more efficient than the orchestration debugger. If you need to write out trace messages containing the XML content of a message you can assign a message instance to a variable of type System.Xml.XmlDocument and then write the OuterXml property to the trace output.

The Data Mapper

• The Mass Copy functoid copies an element and all its children between compatible elements in the source and the destination message.
• The String Concatenation functoid can output constant strings as well. It does not need any input from the source document(s).
• The Looping functoid outputs sequences of the same XML element, i.e. elements where maxOccurs > 1.
• The context menu for a data map file in the Solution Explorer allows to test a map and validate the output against the output schema.

The Schema Editor

• The context menu for an XML Schema file in the Solution Explorer provides options to generate an instance document for the schema. BizTalk stores the generated instance document in the user's temp directory. Use this document as a test input for your orchestrations.
• You can only promote unique leaf nodes to properties. Use the xpath() function if you need to access elements that have XML content or maxOccurs > 1

Decision Expressions

• Decision Expressions have to be simple boolean expressions. You need to perform multi-step computations in expression shapes, not in a Rule shape that belongs to an expression.
• Some type conversions do not happen automatically. You need to explicitly convert types with the .NET Convert class when you see messages telling you
  
  operator XX can not be applied to operands of type 'System.Object' and 'System.Int32'.
  
  If you are trying to branch based on the presence on an element with a XPath query for example, the expression in the Rule shape would be:
  
  System.Convert.ToInt32(xpath( Message_1, "count( //*[local-name()='parent' and namespace-uri()='urn:webservices.com']/*[local-name()='child' and namespace-uri()='urn:webservices.com'])" ) ) > 0

Orchestrations

• Calling the same request-response web service port from parallel execution branches requires surrounding the corresponding send and receive shapes with a scope to synchronize send and receive if there no correlations are set up for the recieve message.
• An orchestration owns the ports and types it defines.
• You cannot export an orchestration to BPEL if it references ports and types defined in an orchestration that is not exportable.
• You get errors and warning that refer to line numbers when you build a BizTalk project. Now, you don't really see any line numbers in the orchestration designer, do you? The line numbers refer to the XLANG/s code in the actual .odx file. If you bring it up as a text file (right click on the file in the Solution Explorer -> Opn With ... and select the HTML/XML Editor) then you can see the lines causing the error.

Debugging

• BizTalk writes debug information to the Windows Event Log. Look there for more information if things don't work the way you expect them to work.
• When a web service returns a fault to an orchestration, the SOAP adapter will repeat the web service call according to the retry settings configured for the Send Location. The details about the fault are written to the Event Log.
• The Orchestration Debugger is accessible from the Health and Activity Monitoring tool, not the Visual Studio IDE.

Hope this helps. Microsoft announces to update the BizTalk documentation quarterly(!). The first update on 4/1/2004 improved the situation somewhat, but there are still lots of wholes in the docs.

Let me know if you feel I should add more items.