BizTalk 2006 Naming Conventions

Scott Colestock / www.traceofthought.net

 

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

Schema file

<RootNode>_<Standard>.xsd or

<DescriptiveName>_<Standard>

Standards include XML, X12, FlatFile (FF) and other custom formats.

 

If root node does not distinguish the schema – or if the schema is for a well-known standard, use descriptive name.

 

 

.NET Type name should match, without file extension. 

 

.NET Namespace will likely match assembly name.

PurchaseOrderAcknowledge_FF.xsd  or

FNMA100330_FF.xsd

Property Schema files

<PropSchema>_<Standard>.xsd

Should be named to reflect its common usage across multiple schemas, if appropriate.

 

PONumber_XML.xsd

Maps

<SourceSchema>2<DestinationSchema>.btm

 

If xslt file spec’d for map, xslt file should be named identically with xsl extension.

PurchaseOrder_FF2PurchaseOrderAcknowledge_XML.btm

Orchestrations

A meaningful name that represents the underlying process, likely with a verb-noun pattern.

 

EvaluateCredit.odx

Send/Receive Pipelines

Rcv_<SchemaName> or

Rcv_<ProjectName> or

Rcv_<Function>

 

Snd_<SchemaName> or

Snd_<ProjectName> or

Snd_<Function>

A pipeline might be used to ensure reception of  particular schema(s), or to perform some other function.  Project name might be used when multiple schemas are spec’d for asm/dasm

Rcv_ PurchaseOrderAcknowledge_FF

Rcv_CatalogUnzip

Receive Ports

A plainly worded phrase that will be clear to operations staff as to function.  No need to use underscores or Pascal-cased dense names.

 

 

 

Sales Orders From Siebel for Great Plains

 

Get Document Number From Warehouse

 

 

Receive Locations

<ReceivePortName>.<Transport>

 

Sales Orders From Siebel for Great Plains.MSMQ

Send Port Groups

Plain phrase for operations group.

 

Customer Updates

Send Ports

A plainly worded phrase that will be clear to operations staff as to function.  No need to use underscores or Pascal-cased dense names.

 

 

Customer Updates for CRM

Parties

A meaningful name for a Trading Partner.

If dealing with multiple entities within a Trading Partner organization, the Organization name could be used as a prefix.

 

Roles

A meaningful name for the role that a Trading Partner plays.

 

Shippers

 

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

Scopes

Scope_<DescriptionOfContainedWork> or

Scope_<DescOfcontainedWork>_<TxType>

 

Including info about transaction type may be appropriate in some situations where it adds significant documentation value to the diagram.

Scope_CreditServiceCall

 

 

 

 

Receive

Rcv_<MessageName>

Typically, MessageName will be the same as the name of the message variable that is being received “into”.

Rcv_rawCreditReport

Send

Snd_<MessageName>

Typically, MessageName will be the same as the name of the message variable that is being sent.

Snd_pOAcknowledge

Expression

<DescriptionOfEffect>

Expression shapes should be named with pascal convention (no prefix) to simply describe the net effect of the expression, similar to naming a method. 

 

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.

GetFindingsReport

Decide

Decide_<DescriptionOfDecision>

Decide shapes should be prefixed with “Decide_” followed by a full description of what will be decided in the “if” branch

Decide_ApprovalRequired

If-Branch

If_<DescriptionOfDecision>

If-branch shapes should be prefixed with “If_” followed by a (perhaps abbreviated) description of what is being decided

If_ApprovalRequired

Else-Branch

Else

Else-branch shapes should always be named “Else”

 

Else

Construct Message (Assign)

Assign_<Message> (for Construct)

 

<ExpressionDescription> (for expression)

If a Construct shape contains a message assignment, it should be prefixed with “Assign_” followed by an abbreviated name of the message being assigned. 

 

The actual message assignment shape contained should be named to describe the expression that is contained.

Assign_PaymentVoucher

 

which contains expression:

CopyPaymentDetails

Construct Message (Transform)

Xform_<SourceSchema>2<DestSchema> (for Construct)

 

X_<SourceSchema>2<DestSchema>

(for expression)

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 destination schema.)

 

The actual message transform shape contained should generally be named the same as the containing shape, except with an “X_” prefix to save space (“X_LoanRequestToCreditRequest). 

 

Xform_LoanRequestToCreditRequest

 

which contains transform shape:

X_LoanRequestToCreditRequest

 

 

 

 

 

 

 

 

Construct Message (containing multiple shapes)

 

If a Construct Message shape uses multiple assignments or transforms, the overall shape should be named to communicate the net effect, using no prefix.

 

 

Call/Start Orchestration

Call_<OrchestrationName>

 

Start_<OrchextrationName>

 

 

Throw

Throw_<ExceptionType>

The corresponding variable name for the exception type should (often) be the same name as the exception type, only camel-cased.

Throw_RuleException, which references the “ruleException” variable.

 

 

Parallel

Parallel_<DescriptionOfParallelWork>

Parallel shapes should be named “Parallel_” followed by a description of what work will be done in parallel

Parallel_CreditVendorCalls

 

Delay

Delay_<DescriptionOfWhatWaitingFor>

Delay shapes should be named “Delay_” followed by an abbreviated description of what is being waited for. 

Delay_POAcknowledgeTimeout

Listen

Listen_<DescriptionOfOutcomes>

Listen shapes should be named “Listen_” followed by an abbreviated description that captures (to the degree possible) all the branches of the Listen shape

Listen_POAckOrTimeout Listen_FirstShippingBid

Loop

Loop_<ExitCondition>

Loop shapes should be named “Loop_” followed by an abbreviated description of what the exit condition is.

Loop_UntilAllMsgsSent

 

Loop_WhileErrorFlagTrue

Role Link

 

See “Roles” in messaging naming conventions above.

 

Suspend

Suspend_<ReasonDescription>

Describe what action an administrator must take to resume the orchestration.  More detail can be passed to error property – and should include what should be done by the administrator before resuming the orchestration.

Suspend_ReEstablishCreditLink

Terminate

Terminate_<ReasonDescription>

Describe why the orchestration terminated.  More detail can be passed to error property.

Terminate_TimeoutsExpired

Call Rules

CallRules_<PolicyName>

The policy name may need to be abbreviated.

CallRules_CreditApproval

Compensate

Compensate

or

Compensate_<TxName>

If the shape compensates nested transactions, names should be suffixed with the name of the nested transaction – otherwise it should simple be Compensate.

 

Compensate_TransferFunds

or

Comp_TransferFunds

 

 

Orchestration Naming Conventions – Orchestration Types

 

Type

Standard

Notes

Example

Multi-Part Message Types

<LogicalDocumentType>

 

Multi-part types encapsulate multiple parts.  The WSDL spec indicates “parts are a flexible mechanism for describing the logical abstract content of a message.”  The name of the multi-part type should correspond to the “logical” document type, i.e. what the sum of the parts describes.

InvoiceReceipt

 

(which might encapsulate an invoice acknowledgement and a payment voucher.)

Multi-Part Messsage Part

<SchemaNameOfPart>

Should be named (most often) simply for the schema (or simple type) associated with the part.

InvoiceHeader

Messages

camelCased

Should be named with camel-cased, based on the corresponding schema type or multi-part message type.  If there is more than one variable of a type, name for its use within the orchestration.

purchaseOrderAck

Variables

camelCased

 

 

Port Types

<function>PortType

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 Type, the Port Type should be named according to the abstract service supplied.

 

The WSDL spec indicates port types are “a named set of abstract operations 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.

ProcessPurchaseOrderPortType

 

which might have operations such as

SubmitPO

RequestPOStatus, etc.

 

Ports

<function>Port

Should be named to suggest a grouping of functionality, with pascal casing and suffixed with “Port.” 

ProcessPurchaseOrderPort

 

 

Correlation types

PascalCased

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

PurchaseOrderNumber

Correlation sets

camelCased

Should be named with camel-case convention based on the corresponding correlation type.  If there is more than one, it should be named to reflect its specific purpose within the orchestration.

 

purchaseOrderNumber

Orchestration parameters

camelCased

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