Geeks With Blogs
Stuart Brierley Integration Management - BizTalk and More

The following BizTalk naming guidlines are heavily based on those proposed by Scott Colestock over at Trace Of Thought.

 As you can see from the link, Scott wrote his naming conventions for BizTalk Server 2006, whereas I am still using BizTalk Serevr 2004.  In reality these guidlines are pretty much universal across any version of BizTalk you may wish to apply them to.

Although the general principles for these guidlines are the same as Scott's, I have made some changes based on personal preference and the conventions that I already had in place.   You may find these interesting as an alternative view on naming conventions for BizTalk.

I would suggest that you have a read of both guidelines on offer, and whether you take one on wholesale or come up with you own flavour for your guidlines, the important thing is that you have some and follow them.

General Rules

All names should be named with a Pascal convention.

Project Namespaces

For message schemas:

[CompanyName].XML.Schemas.[FunctionalName]*

Examples: 

ABC.XML.Schemas.Underwriting

DEF.XML.Schemas.MarshmellowTradingExchange

* Donates potential for multiple levels of functional name, such as Underwriting.Dictionary.Valuation

For web services:

[CompanyName].Web.Services.[FunctionalName]

Examples:

ABC.Web.Services.OrderJellyBeans

For the main BizTalk Projects:

[CompanyName].BizTalk.[AssemblyType].[FunctionalName]*

Examples:

ABC.BizTalk.Mappings.Underwriting

ABC.BizTalk.Orchestrations.Underwriting

* Donates potential for multiple levels of functional name, such as Mappings.Underwriting.Valuations

Assemblies

BizTalk Assembly names should match the associated Project Namespace, such as ABC.BizTalk.Mappings.Underwriting.

This pertains to the formal assembly name and the DLL name.

The Solution name should take the name of the main project within the solution, and also therefore the namespace for that project.

Although long names such as this can be unwieldy to work with, the benefits of having the full scope available when the assemblies are installed on the target server are generally judged to outweigh this inconvenience.

Messaging Artifacts

 

Artifact

Standard

Notes

Example

Schema

<DescriptiveName>.xsd

 

.NET Type name should match, without file extension. 

 

.NET Namespace will likely match assembly name.

PurchaseOrderAcknowledge_FF.xsd  or

FNMA100330_FF.xsd

Property Schema

<DescriptiveName>.xsd

Should be named to reflect possible common usage across multiple schemas 

IspecMessagePropertySchema.xsd

UnderwritingOrchestrationKeys.xsd

Map

<SourceSchema>2<DestinationSchema>.btm

Exceptions to this may be made where the source and destination schemas share the majority of the name, such as in mainframe web service maps

InstructionResponse2CustomEmailRequest.btm

(exception example)

AccountCustomerAddressSummaryRequest2MainframeRequest.btm

Orchestration

<DescriptiveName>.odx

 

GetValuationReports.odx

SendMTEDecisionResponse.odx

Send/Receive Pipeline

<DescriptiveName>.btp

 

ValidatingXMLReceivePipeline.btp

FlatFileAssembler.btp

Receive Port

A plainly worded phrase that will clearly explain the function. 

 

FraudPreventionServices

LetterProcessing

 

Receive Location

A plainly worded phrase that will clearly explain the function.

 ? Do we want to include the transport type here ?

Arrears Web Service

Send Port Group

A plainly worded phrase that will clearly explain the function.

 

Customer Updates

Send Port

A plainly worded phrase that will clearly explain the function. 

 

ABCProductUpdater

LogLendingPolicyOutput

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.

 

 

Orchestration Workflow Shapes

 

Shape

Standard

Notes

Example

Scopes

<DescriptionOfContainedWork> or

<DescOfcontainedWork><TxType>

 

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

HandleReportResponse

 

 

 

 

Receive

Receive<MessageName>

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

ReceiveReportResponse

Send

Send<MessageName>

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

SendValuationDetailsRequest

Expression

<DescriptionOfEffect>

Expression shapes should be named to 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.

CreatePrintXML

Decide

<DescriptionOfDecision>

A description of what will be decided in the “if” branch

Report Type?

Perform MF Save?

If-Branch

<DescriptionOfDecision>

A (potentially abbreviated) description of what is being decided

Mortgage Valuation

Yes

Else-Branch

Else

Else-branch shapes should always be named “Else”

Else

Construct Message (Assign)

Create<Message>

(for Construct)

 

 

<ExpressionDescription>

(for expression)

If a Construct shape contains a message assignment, it should be prefixed with “Create” 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.

CreateReportDataMV

 

which contains expression:

ExtractReportData

Construct Message (Transform)

Create<Message>

(for Construct)

 

<SourceSchema>2<DestSchema>

(for transform)

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

 

The actual message transform shape contained should generally be named the same as the called map. 

CreateReportDataMV

 

which contains transform:

ReportDataMV2ReportDataMV

 

 

 

 

 

 

 

 

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<OrchestrationName>

 

 

Throw

Throw<ExceptionType>

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

ThrowRuleException, which references the “ruleException” variable.

 

 

Parallel

<DescriptionOfParallelWork>

Parallel shapes should be named by a description of what work will be done in parallel

 

Delay

<DescriptionOfWhatWaitingFor>

Delay shapes should be named by a description of what is being waited for. 

POAcknowledgeTimeout

Listen

<DescriptionOfOutcomes>

Listen shapes should be named by a description that captures (to the degree possible) all the branches of the Listen shape

POAckOrTimeout FirstShippingBid

Loop

<DescriptionOfLoop>

A (potentially abbreviated) description of what the loop is.

ForEachValuationReport

WhileErrorFlagTrue

Role Link

 

See “Roles” in messaging naming conventions above.

 

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.

ReEstablishCreditLink

Terminate

<ReasonDescription>

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

TimeoutsExpired

Call Rules

Call<PolicyName>

The policy name may need to be abbreviated.

CallLendingPolicy

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.

CompensateTransferFunds

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

<SchemaName>

or

<MuliPartMessageTypeName>

Should be named 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.

ReportDataMV

UpdatedReportDataMV

Variables

<DescriptiveName>

 

TargetFilePath

StringProcessor

Port Types

<FunctionDescription>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.

ReceiveReportResponsePortType 

or

CallEAEPortType

(This is a two way port, so Receove or Send alone would not be appropriate.  Could have been ProcessEAERequestPortType etc....)

Ports

<FunctionDescription>Port

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

ReceiveReportResponsePort

CallEAEPort

Correlation types

<DescriptiveName>

Should be named based on the logical name of what is being used to correlate. 

PurchaseOrderNumber

Correlation sets

<DescriptiveName>

Should be named 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

<DescriptiveName>

Should be named to match the caller’s names for the corresponding variables where appropriate.

 

Posted on Monday, November 9, 2009 11:47 AM Random Thoughts of Interest , BizTalk Administration and Troubleshooting , BizTalk Infrastructure and Installation , BizTalk Adapters , BizTalk Maps, Mapping and Functoids , BizTalk Orchestrations | Back to top


Comments on this post: BizTalk 2004 Naming Guidelines

# re: BizTalk 2004 Naming Guidelines
Requesting Gravatar...
We went round and round in circles on this when BizTalk 2004 first shipped. I also know that some enterprising people in MS even did work to create extensions for their internal source code testing tools to add rules to check naming conventions for BTS 2004, and they used a similar approach (this is very ancient history now, and I have no idea what became of their work)

To begin with, we took on Scott's naming conventions. However, with more experience of the product we eventually decided that for orchestration shapes the most appropriate thing was to use free-form names with spaces. We originally hoped that a terse Pascal case style would help pack the maximum meaning into the minimum amount of screen real-estate. However, this approach was never satisfactory. Eventually we decided that we would do better just using verbose, description free-form text to name shapes. At least you can read the full names (as long as they are not too long) in your tool tips. On balance, this approach seemed to provide the greatest clarity. So, we eventually codified that approach into our own standards, and have used it across subsequent releases of the product. Slightly counterintuitive, but I see it as the least-worse option.
Left by Charles Young on Nov 09, 2009 6:53 PM

# re: BizTalk 2004 Naming Guidelines
Requesting Gravatar...
Charles,

Thanks for the input. We considered a few different options when deciding on the standards we would adopt, in fact some of our pre-standards orchestrations have free format shape names, but we thought there would be no chance of confusion if we adopted a single naming style across all our BizTalk objects.

Pascal case is also the standard we use for our VB.Net programming, so again this gives us consistency on our Microsoft Development platforms.
Left by Stuart Brierley on Nov 19, 2009 8:32 PM

Your comment:
 (will show your gravatar)


Copyright © Stuart Brierley | Powered by: GeeksWithBlogs.net