BizTalk 2004 Naming Conventions

This document covers proposed naming conventions for describing BizTalk artifacts.

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.

Below are a set of proposed guidelines in this area.

BizTalk Artifact Namespaces
Many artifacts within a BizTalk solution will have a standard .Net namespace associated with them. The standard guidance on .Net namespace naming could be
adhered to with BizTalk artifacts, namely:
CompanyName.TechnologyName.Feature

However, you might also choose:

CompanyName.[FunctionalArea].[Project].BizTalk.[AssemblyType]

(where assembly type is discussed below)

Note that these are Pascal-cased, and nested namespaces will have dependencies on types in the containing namespace.

BizTalk Assemblies
BizTalk Assemblies should often match the name of the associated namespace, such as
CompanyName.TechnologyName.Feature.dll
This pertains to the formal assembly name and the DLL name (which can be different in theory, but shouldn’t be in practice.)

Note that a division into assemblies such as the following will often be quite suitable for a BizTalk project.
MyCompany.MyProject.Orchestrations.dll
MyCompany.MyProject.Schemas.dll
MyCompany.MyProject.Pipelines.dll
MyCompany.MyProject.Transforms.dll
MyCompany.MyProject.PipelineComponents.dll

Note that the Visual Studio solution name will likely be MyCompany.Project.BizTalk in this case.

Long names such as this can be somewhat unwieldy to work with (especially in tools where File dialogs are too narrow.) However, the benefits associated with
having the full scoping available when the assemblies and associated artifacts are encountered “in the wild” (i.e. in a shared BizTalk application environment)
are judged to outweigh the inconvenience.
BizTalk Messaging Artifacts
All names should be named with a Pascal convention unless mentioned otherwise for the specific artifact, although underscores are used to separate logical
entities. For schemas, maps, orchestrations, and pipelines, ensure that the .NET type name matches the file name (without file extension.)

Artifact Standard Notes Example

 Standards include PurchaseOrderAcknowledge_FF.xsd or
XML, X12, FlatFile (FF) FNMA100330_FF.xsd
and other custom PONumber_XML.xsd
formats.
PurchaseOrder_FF_To_PurchaseOrderAcknowledge_X
If root node does not ML.btm
<RootNode>_<Standard>.xsd or
Schema file distinguish the
<DescriptiveName>_<Standard> EvaluateCredit.odx
schema – or if the
schema is for a well-
known standard, use
descriptive name.

Should be named to
reflect its common .NET Type
Property usage across multiple name should
<PropSchema>_<Standard>.xsd match, without
Schema files schemas, if
appropriate. file extension.

.NET
Namespace
If xslt file spec’d for will likely
<SourceSchema>_To_<DestinationSchema>.bt
Maps map, xslt file should match
m Rcv_ PurchaseOrderAcknowledge_FF
be named identically assembly
with xsl extension. name. Rcv_CatalogUnzip

A meaningful name that represents the

Orchestrations underlying process, likely with a verb-noun
pattern.

A pipeline might be
used to ensure
Rcv_<SchemaName> or
reception of
Rcv_<ProjectName> or
particular schema(s),
Rcv_<Function>
Send/Receive or to perform some
Pipelines other function.
Snd_<SchemaName> or
Project name might
Snd_<ProjectName> or
be used when
Snd_<Function>
multiple schemas are
spec’d for asm/dasm

Receive Ports <BizApp>_<InputSchema>_To_<OutputSchema ‘BizApp’ prefix (corresponding to ERP_PurchaseOrder_XML_To_POAck_XML

> name of the app deploying to (for request/response port)
or BizTalk) helps when many
<BizApp>_<FunctionalDescription> applications are deployed to the ERP_PurchaseOrder_XML
 same BizTalk installation.

Use functional description if the

input schema (and potentially output
(for one-way port)
schema, if request/response) do not
(One-way ports use functional description form) adequately describe the port.
ERP_CheckOrderStatus
(No need to add Snd/Rcv/Port, etc.
since they are grouped accordingly
in admin tools)

Receive
<ReceivePortName>_<Transport> ERP_CheckOrderStatus_MSMQT
Locations

Send Port ‘BizApp’ prefix – see Receive Ports.

<BizApp>_<FunctionalDescription> CRM_CustomerUpdateNotification
Groups

In some cases, the schema being

<BizApp>_<Schema>_<Transport>
sent is descriptive enough. In
or
Send Ports others, a functional description of CRM_CustomerUpdate_ERP_MSMQT
<BizApp>_<FuncDescription>_<DestApp>_
the action to be taken by a
<Transport>
destination app is better suited.

If dealing with multiple entities

within a Trading Partner organization,
Parties A meaningful name for a Trading Partner.
the Organization name could be used
as a prefix.

A meaningful name for the role that a Trading

Roles Shippers
Partner plays.

Orchestration Naming Conventions – Workflow Shapes

Note: To add documentation to a group of related workflow shapes, use a Group shape. These will display as much text as you care to associate with them, and
can add quite a bit of documentation value to the diagram. (Shape names should always follow Pascal casing after the prefix that is specified below.)

Shape Standard Notes Example

Scope_<DescriptionOfContainedWork> or Including info about transaction type may be appropriate in

Scopes Scope_<DescOfcontainedWork>_<TxType> some situations where it adds significant documentation Scope_CreditServiceCall
value to the diagram.

Typically, MessageName will be the same as the name of the

Receive Rcv_<MessageName> Rcv_rawCreditReport
message variable that is being received “into”.

Send Snd_<MessageName> Typically, MessageName will be the same as the name of the Snd_pOAcknowledge
 message variable that is being sent.

Expression shapes should be named with pascal convention

(no prefix) to simply describe the net effect of the
expression, similar to naming a method.
Expression <DescriptionOfEffect> GetFindingsReport
The exception to this is the case where the expression is
interacting with an external .NET component to perform a
function that overlaps with existing BizTalk functionality –
use closest BizTalk shape for this case.

Decide shapes should be prefixed with “Decide_” followed by

Decide Decide_<DescriptionOfDecision> Decide_ApprovalRequired
a full description of what will be decided in the “if” branch

If-branch shapes should be prefixed with “If_” followed by a

If-Branch If_<DescriptionOfDecision> If_ApprovalRequired
(perhaps abbreviated) description of what is being decided

Else-branch shapes should always be named “Else”

Else-Branch Else Else

If a Construct shape contains a message assignment, it

should be prefixed with “Assign_” followed by an abbreviated Assign_PaymentVoucher
Construct Assign_<Message> (for Construct)
name of the message being assigned.
Message
which contains expression:
(Assign) <ExpressionDescription> (for expression)
The actual message assignment shape contained should be CopyPaymentDetails
named to describe the expression that is contained.

If a Construct shape contains a message transform, it should

be prefixed with “Xform_” followed by an abbreviated
description of the transform (i.e source schema to
Xform_<SourceSchema>To<DestSchema>
destination schema.) Xform_LoanRequestToCreditRequest
Construct (for Construct)
Message
The actual message transform shape contained should which contains transform shape:
(Transform) X_<SourceSchema>To<DestSchema>
generally be named the same as the containing shape, X_LoanRequestToCreditRequest
(for expression)
except with an “X_” prefix to save space
(“X_LoanRequestToCreditRequest”).

Construct If a Construct Message shape uses multiple assignments or

Message transforms, the overall shape should be named to
(containing communicate the net effect, using no prefix.
multiple
shapes)

Call/Start Call_<OrchestrationName>
Orchestration
 Start_<OrchextrationName>

The corresponding variable name for the exception type Throw_RuleException, which references
should (often) be the same name as the exception type, only the “ruleException” variable.
Throw Throw_<ExceptionType>
camel-cased.

Parallel shapes should be named “Parallel_” followed by a Parallel_CreditVendorCalls

Parallel Parallel_<DescriptionOfParallelWork>
description of what work will be done in parallel

Delay shapes should be named “Delay_” followed by an

Delay Delay_<DescriptionOfWhatWaitingFor> Delay_POAcknowledgeTimeout
abbreviated description of what is being waited for.

Listen shapes should be named “Listen_” followed by an

Listen_POAckOrTimeout
Listen Listen_<DescriptionOfOutcomes> abbreviated description that captures (to the degree
Listen_FirstShippingBid
possible) all the branches of the Listen shape

Loop shapes should be named “Loop_” followed by an Loop_UntilAllMsgsSent

Loop Loop_<ExitCondition> abbreviated description of what the exit condition is.
Loop_WhileErrorFlagTrue

Role Link See “Roles” in messaging naming conventions above.

Describe what action an administrator must take to resume

the orchestration. More detail can be passed to error
Suspend Suspend_<ReasonDescription> Suspend_ReEstablishCreditLink
property – and should include what should be done by the
administrator before resuming the orchestration.

Describe why the orchestration terminated. More detail can

Terminate Terminate_<ReasonDescription> Terminate_TimeoutsExpired
be passed to error property.

Call Rules CallRules_<PolicyName> The policy name may need to be abbreviated. CallRules_CreditApproval

If the shape compensates nested transactions, names should

Compensate be suffixed with the name of the nested transaction – Compensate_TransferFunds
Compensate or otherwise it should simple be Compensate. or
Compensate_<TxName> Comp_TransferFunds

Orchestration Naming Conventions – Orchestration Types

Type Standard Notes Example

 Multi-part types encapsulate multiple parts. The WSDL spec indicates “parts InvoiceReceipt
Multi-Part <LogicalDocumentType are a flexible mechanism for describing the logical abstract content of a
Message > message.” The name of the multi-part type should correspond to the (which might encapsulate an invoice
Types “logical” document type, i.e. what the sum of the parts describes. acknowledgement and a payment
voucher.)

Multi-Part Should be named (most often) simply for the schema (or simple type)
<SchemaNameOfPart> InvoiceHeader
Messsage Part associated with the part.

Should be named with camel-cased, based on the corresponding schema type

Messages camelCased or multi-part message type. If there is more than one variable of a type, purchaseOrderAck
name for its use within the orchestration.

Variables camelCased

Should be named to suggest the nature of an endpoint, with pascal casing

and suffixed with “PortType”. If there will be more than one Port for a Port
ProcessPurchaseOrderPortType
Type, the Port Type should be named according to the abstract service
supplied.
which might have operations such as
Port Types <function>PortType
SubmitPO
The WSDL spec indicates port types are “a named set of abstract operations
RequestPOStatus, etc.
and the abstract messages involved” that also encapsulates the message
pattern (i.e. one-way, request-response, solicit-response) that all operations
on the port type adhere to.

Should be named to suggest a grouping of functionality, with pascal casing ProcessPurchaseOrderPort

Ports <function>Port and suffixed with “Port.”

Correlation Should be named with pascal-case convention, based on the logical name of
pascalCased PurchaseOrderNumber
types what is being used to correlate.

Should be named with camel-case convention based on the corresponding

Correlation correlation type. If there is more than one, it should be named to reflect its
camelCased purchaseOrderNumber
sets specific purpose within the orchestration.

Orchestration Should be named with camel-case convention, and match the caller’s names
camelCased
parameters for the corresponding variables where appropriate.