(See here for
the current version of the naming conventions!)

One of the primary benefits of the BizTalk Orchestration model is the great transparency
you can get when a software implementation is pictorial.

Regardless of how well a developer comments code, there will always be a need
to maintain a separate set of artifacts (UML diagrams, Visio diagrams with random
shapes of your choosing, prose documents, whiteboard discussions, etc.) that are used
to convey what the code is actually doing especially when working with a business
audience.  This is true if for no other reason than that a discussion of interesting
functionality will often take place at a different level of granularity than raw code
can support

Round-trip engineering tools – that attempt to keep code in sync with diagrams often
seem to suffer from a lack of fidelity that renders them ineffective.

With BizTalk Orchestration, the diagram is the implementation (at least at
a particular level) of a piece of functionality.  Yes, you can disappear into
components and lose sight of what might happen.  Yes, there is a code representation
(xlang/s) underneath the orchestration but it seems to be completely isomorphic with
the diagram.

So the opportunity exists to use an orchestration diagram in several interesting ways
within a project lifecycle:

1. As a way to capture an initial high-level design, using all the orchestration shapes
   as intended but not yet bothering with real maps and schemas.  Stubbing out schemas
   (so you can declare messages and variables to be of proper types) and maps will allow
   you to flesh out the orchestration diagram(s) quite a bit, using the compiler as just
   a way to check for consistency.  All of the external system interactions, communication
   patterns, decision points, parallel vs. joined flows, etc. can be represented at this
   point in a shell orchestration.

2. As a way to gain consensus with the development team & business sponsor about
   whether the right functionality is indeed going to be built.  The high level
   design just described is a great tool for this discussion.  Put your orchestration(s)
   up on a wall with a projector and do a walk-through with as many of the project stakeholders
   as makes sense.  Or use a tool like CutePDF to
   print the orchestration as a PDF to send around via email.  (Of course, once
   Microsoft ships the Visio add-on for BizTalk 2004 orchestrations, this will represent
   another option for non-VS.NET users.  This has the added benefit of allowing
   you to exclude what you might consider to be lower-level detail by setting the Report
   to Analyst switch on various orchestration shapes to False.)

3. As a way to estimate work.  The various shapes in your initial orchestration
   can often represent reasonable granularity for time estimates.

4. And finally, as a way to guide project work…Rather than starting with the entire
   orchestration that you created to support steps 1-3, you might find it easier to create
   a new orchestration that represents the path(s) you are tackling at a particular point. 
   You can cut/paste portions of that original orchestration or simply use it as a reference
   for what comes next it serves as your outline.

To help realize some of these benefits, naming conventions within an orchestration
are quite important

While the naming conventions are good practice for variables, Messages, Multi-Part
types, etc. they are even more import for the workflow shapes.  The goal is to
ensure that the intent of each shape is clear, and that the text associated with the
shape conveys as much as possible given the space constraints.  In this way,
a non-technical audience will be able to use the orchestration as documentation.

(See here for
the current version of the naming conventions.)

Respond with comments & the document will remain updated per your feedback!

I intend to cover some more foundational material for BizTalk
2004 in the future, but today I wanted to cover an issue that at least some people
will run into fairly quickly when beginning to use the product.

There are times when it is desirable to work with multiple XML schemas that specify
the same target namespace, and which specify different definitions for the same element.

For instance, you may wish to have a lax schema when a document lands on your doorstep
initially – but further into the processing of that document (along a particular path)
you may wish to validate against a stricter schema.  Or, you may have a situation
where you have what is arguably an envelope structure which can’t be cleanly stripped
off (for a variety of reasons) – leaving you with documents which might look quite
different, but have the same target namespace and element usage.

BizTalk 2004, in general, wants to see one schema deployed to the BizTalk management
database for any given combination of target namespace and element declaration. 
If you deploy two schemas with target namespace http://MyNamespace and element declaration
MyRoot, and then attempt to receive a MyRoot-rooted document through a receive port
using the default Xml Receive pipeline, you will receive an error from BizTalk like
this one:

There was a failure executing the receive pipeline…Source:"XML Disassembler"…
Reason: The disassembler cannot retrieve the document specification using this type:
"http://MyNamespace#MyRoot". Either the schema is not deployed correctly,

or more than one schema is deployed for the same message type.

To overcome this, you can use custom BizTalk Pipelines on the send and receive ports
that will be dealing with schemas that are subject to the ambiguity.  Within
a pipeline, you can restrict the set of available schemas from “everything that is
deployed” down to the schema(s) that you are interested in.

Specifically, for receive ports, you can add a new item to your project (a “Receive
Pipeline”), and add the default Disassembler and Party Resolution pipeline components. 
For the Disassembler component, edit the “Document Schemas” collection and add the
particular schema you are interested in.  See this picture for
an illustration.

Likewise, for send ports, you can add a “Send Pipeline” item to your project, and
add the default Assembler pipeline component.  Again, specify the schema you
are interested in with the “Document Schemas” collection of the Assembler.

For each of the Send or Receive ports that will be trafficking in these messages,
specify your newly created pipelines – instead of the default Xml Receive/Send pipelines! 

Now for the gotchya! (you knew there had to be one, right?)

BizTalk 2004 will require that the assembly containing your custom pipeline(s) is
deployed to the GAC (along with every other BizTalk project assembly.)

When components loaded from the GAC wish to dynamically load other types & assemblies,
they must do so with fully qualified assembly names.  Applying this to our current
discussion means this: BizTalk pipelines must have fully qualified information for
the assembly that contains the schemas you configure within pipeline components.

If the pipeline component lives in the same BizTalk project as the schemas you are
attempting to reference, the property designer (when editing the “Document Schemas”
collection) will only be populated with a namespace-qualified type name – the fully
qualified assembly name will be missing.  At run time, the schemas will not be
found…and the behavior at run time will appear completely unchanged from the
case where no custom pipeline was specified at all. 

To work around this, simply put your pipelines in a different project/assembly
than the project containing the schemas you need to reference in the designer.

A bug you say?  Certainly it would be nice if the designer warned you,
and it deserves a KB article soon…But keep in mind what is happening: 
A GAC-destined component (a pipeline Disassembler) is providing designer support which
allows you to select another component (a schema) which will be loaded dynamically
at run time…It raises an interesing problem that goes beyond just BizTalk 2004.

Whenever a component that is destined for the GAC has IDE designer support which
in turn allows you to select a type for a “plug in” component that will be loaded
by the “host” component dynamically at run time (without using Assembly.LoadFrom
semantics) – you will run into this issue.  Why?  Because if you select
a type from the same project, the fully qualified name can’t be reliably
known.  After all, the project might not have been compiled yet, or the fully-qualified
name might be set up to change with each compilation (gasp!) via 1.0.*.* versioning
policy.  If you use such a designer to select a type in a distinct assembly,
the fully qualified name can indeed be known -and shame on the component author if
the versioning policy isn’t sane.

Of course, being deployed into the GAC raises all kinds of thorny issues, but this
one was a bit subtle…