BizTalk Orchestration Naming Conventions

Article
1/17/2024

[last update: 2015-02-12]

Simple Conventions

Always follow the KISS principle in names. It doesn't make sense to standardize names only for sake of standardization. It is easy to create a complicated convention, it is hard to create a simple convention. We get complexity for free. These conventions do not limit you in naming the most of the shapes. Only several shape names are defined and they are defined in the minimalistic way. As a result, we can read and write the orchestrations without much ceremony.

There is a big difference between names inside orchestration and names of other BizTalk artifacts. Many BizTalk artifacts work in a global namespace hence they required complex hierarchical names. Names inside orchestration are mostly limited to the project namespace, hence hierarchical names can be thrown away, the complex naming conventions can be replaced by simple rules. Moreover, name consistency rules should not be forced too hard.

Special Orchestration Objects

<Message> =: msg_ + <MessageLogicalName>

<Variable> =: var_ + <Word>

<CorrelationSet> =: cor_ + <Word>

<OrchestrationParameter> =: par_ + <Word>

<RoleLink> =: roleLink_ + <Word>

<PortIdentifier> =: <prefix>_<Name>

where <prefix> is S or R or SR or RS
for Communication pattern: Send, Receive, Send-Receive (Solicit-Response), Receive-Send (Request- Response)

Orchestration Object Types

<PortType> =:

<Multi-partMessageType> =:

<CorrelationType> =:

<RoleLinkType> =: <LogicalName>_type

Shape Names

<Receive> =:

<Send> =:

**<Constuct> =: **<MessageLogicalName>

<Transform> =:

<Assignment> **=: ** from <MessageLogicalName>

Notes:

Special Orchestration objects are used in different XLang language context and sometimes they use different language syntax. Prefixes help to differentiate the objects in the XLang expressions.
Prefixes for the Special orchestration objects work better than suffixes, because they are mostly used in the XLang expressions with IntelliSense. Start type with "msg", hit the Ctrl-Space and choose your message. Prefixes are very helpful.
The Port objects are the only objects which can be seen outside Orchestration Editor. We see them as the Port Identifiers while binding Orchestrations with Ports in the BizTalk Administration Console. Sometimes the orchestration Ports Shapes are named as Logical Ports and the Ports as the Physical Ports. Here are some considerations about this ambiguity with Port names.
Send-receive prefixes (S_, RS_ ...) help while binding the Orchestration with Ports. Ports with different Communication pattern are using different prefixes.
Example: S_ OrderAck.
We see the orchestration object types in the Orchestration View window, in Types. They are: Port, Multi-part Message, Correlation and Role Link Types. We can use one suffix the “_type” for all different types because different types are seen only in the different lists and never mixed. For instance, we can never see the port types together with message types.
Suffixes for the orchestration object types work better than prefixes, because types are mostly used in the drop-down lists not in the XLang expressions.

Orchestration Workflow Shapes

Problems with orchestration shapes

Shapes are too small to display long names (only 12-18 characters are visible).
We have to hover a mouse over a shape or click shape to show Properties window to "understand" this shape, to understand what message is processed here.

Discussions

Shapes have names that we see on the Orchestration Editor space, but these names are not the “variable names”, not identifiers. They are descriptions (excluding the Port shapes names, which have not Name parameter but Identifier and Description parameters). Shape names are used only for description not as XLang variable identifiers. Shape names can be long and can include any symbols as spaces, dots, etc. Feel free to use **spaces **and any other symbols inside the shape names.
Shape Icons give us plenty information. Do not repeat the “icon information” by words. For example, we can name a Construction shape as “Construct OrderAck” or as “OrderAck”. Last variant give us clean and short definition plus we see the Construction shape icon so no need in the Construction suffix.
Shape names used mainly in the Orchestration Editor (excluding the Port shapes names). So, we don’t need “well-sorted” names, we don’t need to use prefixes, because the main purpose of the prefixes is in creating well-sorted lists.
Group shape has a resizible shape. Nesting other shapes into a Group shape makes a long description visible. Group shape will display as much text as you want. Grouping of the shapes adds a lot of documentation value to the orchestration.
Purpose of the orchestration and the most of the shapes is in visualizing the processing of the messages. We can unambiguously describe messages by a message type. A message type gives us the main information about a message. That is why in the most cases using the message type as the shape name gives us the main information about message flow, about the whole orchestration processing.

Note: When an exception is thrown from a shape, the error description includes a name of the shape. When we use MessageType as a name of shapes, several shapes can get the same name. So, if we want to differentiate shape names for debugging we could use numbers or single letters in the end of names. Example: “OrderAck 2”.

Share via