BizTalk 2004 Naming Conventions
“Scott Colestock” <scolestock@community.nospam> wrote in message news:eeY5KIjEGHA.984@tk2msftngp13.phx.gbl…
> In general, try using more “Group” shapes to make orchestrations more
> self-documenting…
>
> A general text annotation feature in the designer would be great, wouldn’t
> it?
Of course I use it, but not on each shape!
You know, name of the most shapes can be based ONLY on the names of the schemas. Usualy all what we want to know in orchestrations it’s the “message flow” and “message transformation”. Think of that.
Schemas give us the main information about the messages. Icon information is enough to understand what exactly happened in shape under the messages: send, receive, mapping, etc.
If I’m working with the Orch which was created by somebody else, the standard way to review this orch is:
* look for the message of the shape (click the shape and see the properties)
* look for the schema of these messages (click the message and see the properties)
We have to click, click, click… Why?
If creator of the Orch uses the proposed naming convention all these steps disappeared. We can see exactly the “schema flow” and “schema transformation”.
…
Goals:
l
Readable namesl
Unambiguous namesl
Fast-created names (using Copy-Past)l
Fast search in the lists of BizTalk Explorer, Visual Studio and BizTalk Administration Manager
Chapter 1: Names of artifacts in Orchestrations
Problem with shape names in Orchestrations:
Shapes too small to display long names (12-18 chars).
Frankly it was the main goal this document to take into consideration this problem. If we use the “BizTalk 2004 Naming Conventions” by Scott Colestock
http://www.traceofthought.net/misc/BizTalk%20Naming%20Conventions.htm
the result is pity, we create too long names.
L We have to “hover mouse over” shape or click shape to show Properties window to “understand” this shape. The names are complicated.Useful features:
l
Shape names are not the “real names”. In reality they are the descriptions (excluding the Port shapes names). It means we can give the same names to the different shapes without conflicts and we can use spaces inside the names.l
Icons of shapes give us the useful information. We have icons and don’t have to repeat the purpose the shapes by words. For example, if we change a name of Construction shape from “Construct Input message” to “Input message” we get more clear definition because we have the Construct icon + name. Unfortunately the meaning of the icons sometimes is not so clear. For example, the icons on the Send and Receive shapes look as mistaken: the arrow on Send shape icon points “inside” and the arrow on Receive shape points “outside”. But it’s the matter of habit. (This is another naming problem in BizTalk. See http://geekswithblogs.net/leonidganeline/archive/2006/12/18/101541.aspx)l
Shape names are not used in any list (exclude the Port shapes names). We don’t have to use any rules to make the “well-sorted” names (it’s the main purpose of the prefixes)
Generic rules:
%u00b7
Purpose the most of the shapes is processing the messages. We can unambiguous describe the messages by they type that’s mean by they schema. That is why in the most cases using the schema names as the message names gives us the main information about this message. That is why in the most cases using the schema names as the shape names give us the main information about this shape. Send shape with name “ASC_X12_311” means … exactly!%u00b7
Names of objects start from Capital letter and other names start from the small letters.For example: [Send]“Account”, [Create Account]”from Order”
%u00b7
Don’t repeat the meaning of shape icon by word.For example:
not “construct Account”[name of Construct shape] + “transform Order to Account”[name of Transform shape inside this Construct shape]
but “Account” + “from Order”
%u00b7
Don’t repeat words from outside shape into the inside shape.For example:
not “Account”[name of Construct shape] + “Order to Account”[name of Transform shape]
but “Account” + “from Order”
%u00b7
Use spaces into the shape names.%u00b7
Use “_” [underscore] into the names of messages and variables and into the Ports and Port types.Messages and variables (Orchestration view):
= “msg_” + schema name of this message without all namespace prefixes or .NET class
For example: msg_ReportDiseases_request
if type of this message is PHSA.RCD.Orchestrations.ReportDiseases.ReportDiseasesService_.ReportDiseases_request
Note: it’s easy to set and maintain this name: just copy last part of it from Properties/Type field to Properties/Name field.
= “var_” + name
For example: var_XmlDocument
if type of this variable is System.Xml.XmlDocument .NET object
Note: it’s easy to set and maintain this name: just copy last part of it from Properties/Type field to Properties/Name field.
Note: we can use the message and variable names without prefixes like mentioned but it is more readable to use it.
Construct, Receive and Send shapes:
= name of constructed message (usually it is the schema of the message) without “msg_” prefix.
For example: ORU_Modified
Note: it’s easy to set and maintain this name: just copy part of it from Properties/Messages Constructed to Properties/Name. For example: From “msg_ORU_Modified” copy “ORU_Modified”
Transform shapes:
= “from “ + name of Source message
For example: from ORU
Note: it’s easy to set and maintain this name: just copy it (or part of it) from Properties/Input Messages to Properties/Name. For example: From “msg_ORU” copy “ORU”
Assignment shapes:
No strict rules, only advice:
Name it like the methods in classes. But cut a verb if it possible. Use “set” and “get” if it possible.
For example: “set segment OBX”
Other shapes:
Use the short names. They could fit the name space of the shapes.
Names of the Port shapes:
Notes:
%u00b7
The Port shapes are the real names! We can’t use spaces inside.%u00b7
In the Orchestration view there are lists “Ports” and “Port types” that we have to distinguish the ports with different Communication directions and pattern into these lists.%u00b7
We can’t use the same name for the ports and for the port types.Rule for the Ports:
Send port | Receive port | Send-Receive port (Solicit-Response) | Receive-Send port (Request-Response) | |
Port: | S_ + | R_ + | SR_ + | RS_ + |
Note: it’s easy to set and maintain this name: just copy it from Properties/Port type to Properties/Name. For example: From “S_Account_Type” copy “S_Account”
Rule for the Port types:
+ _Type
Does somebody have any comments? It would be realy appreciated…