BizTalk: Naming convention for the BizTalk solutions

by | Jul 31, 2009 | BizTalk Community Blogs via Syndication | 0 comments

Version 2.0, 2009-07-30
1 How to use this document
To accommodate this document for the specific solution:
%u00b7 Create the real names in Appendix or create a separate Dictionary document. See Instructions in Appendix.
%u00b7 Review the text, marked with [TBD] flag, and change it for your case.
The “Naming guidelines for the .NET Framework types” [ http://msdn.microsoft.com/en-us/library/xzf533w0(VS.71).aspx ] are used as a basis of this document. Also see the “Naming Convention” in Wikipedia [ http://en.wikipedia.org/wiki/Identifier_naming_convention ]
Names should be short, sortable, readable, discoverable, and self-described.
The main test for constructing name rule should be in questions:
%u00b7 In what kind of places can I see this name?
%u00b7 How easily can I work with the names in these places?
“Work” means to read, to find, and to understand sense without errors. Usually we work with names in lists. Think about these places like about namespaces in programming languages.
Short names:
  • Create as short as possible name.
  • Use abbreviations only in restricted cases. See article the “Abbreviations”http://msdn.microsoft.com/en-us/library/141e06ef(VS.71).aspx
  • Use prefixes and suffixes only to differentiate names.
  • If you see one word in several places of the full name, consider this as a bad signal. Try to redesign the terms used in the names.
Sortable:
  • Create “sortable” name. That means using more generic/important part of the name in the leftmost position. For example, prefer the name Folder_20090515 than the name Folder_05_15_2009.
Readable:
  • Use the name case compatible with the well-known practices in programming languages/protocols with respect to upper and lower cases. For instance, the target namespaces (URL) should be in lower case format, but the other names should be in the Pascal format. See the “Capitalization Styles” article [http://msdn.microsoft.com/en-us/library/x2dbyw72(VS.71).aspx ]
    If the word with specific case is widely used in company, don’t force to change it to the Pascal format.
  • Decorate infixes, prefixes or suffixes with lower case and with undrscore. For example: TicketBatch_type, Source1 _and_Source2_to_Target, msg_MyRequest.
Discoverable:
  • The name should be discoverable. That means we easily should understand by the name of the artifact where we can find the artifacts or additional information about it. Names should link artifacts. Say, the schemas with target namespace the http://domain.company.com/solution/project/2009-05-14 definitely should be in the project the Company.Domain.Solution.Project and in assembly the Company.Domain.Solution.Project.dll.
Self-described (Semantics):
  • Create name form the “business point of view” not form the “developer point of view”, especially the name exposed outside solution.
  • Don’t use generic terms in the names. Examples: Send, Receive, Service, Message, Transformation, Schema, Map, Orchestration, BizTalk.
  • Place a frequently used term into the shared dictionary with comment about where do use it and do not use.
  • Several artifacts have the full names (composited names) and short names. Usually we can easily understand what name we use in the specific context.
%u00b7 If we need to add one or more logical grouping into the name, use the composited names created with words separated with dot. In specific contexts the separation symbol can be different, like underscore, dash or backslash. Each <ShortName> can be a composite name. Composite names can be used for each part of the full names, as Company, Domain, Solution, and Project. For example, you can use name the Schemas.Niem for the project short name.
3 General names
3.1 Syntax
<Company>
<Domain>
<Solution> =:
<Company>.<Domain>.<SolutionShortName>
<Project> =:
<Solution>.<ProjectShortName>
3.2 Examples
%u00b7 Solution name: short name –MySolution, full name – MyCompany.MyDomain.MySolution
%u00b7 Project name: short composite name – Schemas.Niem; full name – MyCompany.MyDomain.MySolution.Schemas.Niem
4 Names inside BizTalk Solutions
We use term the solution in the Visual Studio meaning, it is a name of the solution we see in the Solution Explorer window in the Visual Studio. Sometimes we mix solution and project terms but not in this document.
BizTalk application is named as solution.
<Solution> =:
<Company>.<Domain>.<SolutionShortName>
<ApplicationName> =: <Solution>
For example, for the MySolution solution use the MyCompany.MyDomain.MySolution full name.
4.2 Projects, Assemblies, .NET namespaces
We use term the project in the Visual Studio meaning, it is a name of the project we see in the Solution Explorer window in the Visual Studio.
<Project> =:
<Solution>.<ProjectShortName>
<AssemblyName> =: <Project>
<Namespace>=: <Project>
For example, for the MyProject project use the MyCompany.MyDomain.MySolution.MyProject project full name, the MyCompany.MyDomain.MySolution.MyProject assemblyname, and the MyCompany.MyDomain.MySolution.MyProject namespace.
We should separate the .NET namespaces and the target namespaces. They are different things and used in different places. For brevity we use term the namespace exactly for the .NET namespace!
Note: After creating a new project, copy the project name property to the project properties the “Assembly Name” and the “Default Namespace”.
Use the predefined folder structure on all development machines and, if it is possible, on the Test and Product servers. This eliminates the errors and deployment effort because several BizTalk artifacts use the absolute file paths in configuration.
<SolutionsRootFolder> =: c:\Solutions
<SolutionFolder> =:
<SolutionsRootFolder>\<Solution>
<ProjectFolder> =:
<SolutionFolder>\<ProjectShortName>
For example, the MyCompany.MyDomain.MySolution.MyProject project is placed in the c:\Solutions\MyCompany.MyDomain.MySolution\MyProject folder.
Use very strict rules for the target namespaces, because the XML schemas expose the data interfaces to the outer world. The target namespaces should follow the industry standards and the corporate standards. Because the exposed interfaces are immutable, we should use versioning for target namespaces.
We must use the URL and URN formats to target namespaces. Feel free to use one of these standards. See the “Namespaces in XML 1.0 (Second Edition)”http://www.w3.org/TR/xml-names/ for more information.
[TBD: Here I use the URL reverse order for the target namespaces. Not for the full name but for the “before-solution” part of the name, for the first part of the name before first backslash. If you don’t want to use target namespaces that works as the web addresses, consider to use the target namespaces in the generic, nonreversible, sortable order.]
We do compose the URLs in the reversal order like http://domain.company.com/solution/schemas/2009-05-15 and add the “com” part of URL.
<TargetNamespace> =:
http://<Domain>.<Company>.com/<SolutionShortName>/<ProjectShortName>/<Version>
<Version> =:
<date>
[in YYYY-MM-DD format]
[TBD]We considered using the version in two formats. One format is like 1.0.0.1, the format used for the .NET assemblies. See http://msdn.microsoft.com/en-us/library/51ket42z.aspx . The second version format uses a date. Use the first one only if you want a strict versioning rules, and in this case you have to create some version approval procedure. We use here the date format.
  • All schemas in one project use the same target namespace. Schemas in one project with equal target namespace are differentiated by the root node names. Do not place the root node name inside the target namespace.
  • Use the project creating date for the first versions of all schemas inside project.
  • Use the current date for the second and next versions.
  • Create the new version only if the old one is published to production (test) environment. Do not create new versions inside development cycles.
  • Use the YYYY-MM-DD date format to make the names “sortable”. Do not use MM/DD/YY format.
For example, for the MyCompany.MyDomain.MySolution solution and the MyProject project the target namespace should be the http://mydomain.mycompany.com/mysolution/myproject/2009-05-15 for the first versions of all schemas, if this project was created in 2009-05-15.
6 BizTalk artifacts
6.1 Orchestrations, Schemas, Pipelines
Names of these artifacts appear together with BizTalk application name mostly everywhere. We don’t need to use composite names. Use simple names for the names.
Note: If you see one word in several places of the full name, consider this as a bad signal. Try to rethink the terms used in the names. I repeat this rule here, because exactly in the full names of orchestrations, schemas and pipelines you can frequently see repetitive words.
6.2 Maps
<Map> =:
<SourceSchema>_to_<DestinationSchema>[for one-to-one map]
<SourceSchema1>_and_<SourceSchema2>_to_<DestinationSchema>[for two-to-one map]
If it is possible do not change the schema names in the map name. If the map name is excessive long, cut the schema names, but use the same cut rule for all map names.
6.3 Ports
Ports are the primary artifacts of the BizTalk solution. But in contrast to orchestrations they are used through the BizTalk application boundaries in many places, that is why, we have to use the composite names for the ports like for assemblies.
<Port> =:
<Solution>.<PortShortName>
Do we need to separate one and two-way ports and send and receive ports, for example be “R_” or “SR_” prefixes? Do they mix up in lookups or in lists? No. And answer to the first question is “No”, do not use prefixes in the port names.
Do we have to use the transport/protocol qualifiers in the port names, like .FILE or .SOAP? No. One port could use several protocols. Moreover port is on the upper level architecture than transport. But for dynamic ports the transport name can be the main part of the port name.
Do we have to use message type in the port names, like .Request? No. One port could work with several message types. But frequently the message type can be used for the port name.
Try to understand the main purpose of the port and use it in the name. For example, link the port name with transport for dynamic port; or link the port name with the partner name, or with message type.
For example, MyCompany.MyDomain.MySolution.MyPartner.
Use the prefixes to differentiate the artifacts in the XLang expressions. These artifacts are not usual .NET objects. They are used in different language context and sometime they use different language syntax. Prefixes really help to work with these artifacts.
<MessageName> =:
msg_ + <ShortMessageType>
<VariableName> =:
var_ + <Name>
<CorrelationName> =:
cor_ + <Name>
<OrchestrationParameter> =:
par_ + <Name>
<RoleLink> =:
roleLink_ + <Name>
7.2 Orchestration artifact 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.
<ArtifactType> =:
<ArtifactName> + “_type”
<PortName> =:
<prefix> + <Name>
where
Send port
Receive port
Send-Receive
(Solicit-Response)
port
Receive-Send
(Request- Response) port
prefix
S_+
R_+
SR_+
RS_+
For example, S_ OrderAck.
Notes:
  • The Port shapes are the real names, the names of the .NET objects. We can’t use spaces inside.
  • In the Orchestration view there are generic lists “Ports” and “Port types” that’s why we have to distinguish the ports with different Communication directions and pattern.
7.4 Orchestration Workflow Shapes
Problems with orchestration shapes:
%u00b7 Shapes are too small to display long names (only 12-18 characters).
%u00b7 We have to “hover mouse over” shape or click shape to show Properties window to “understand” this shape, to understand what message it is processed.
Useful features:
%u00b7 Feel free to use the same names for different shapes and use spaces inside the shape names. Shape names are not the “real programming names”. In reality they are the descriptions (excluding the Port shapes names); they are used only for description and for nothing more.
%u00b7 Icons on shapes give us the useful information. Do not repeat the “icon information” 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.
%u00b7 Shape names are used only in Orchestration Editor (excluding the Port shapes names). We don’t have to force any rules to make the “well-sorted” names (it’s the main purpose of the prefixes).
%u00b7 Use a Group shape to add description to a group of related workflow shapes.Group shape will display as much text as you want. Group shapes add a lot of documentation value to the orchestration.
7.4.1 Rules for shapes
Purpose of the orchestration and the most of the shapes is in processing the messages. We can unambiguously describe the messages by the message type. That is why in the most cases using the message type names gives us the main information about this message. That is why in the most cases using the message type names as the shape names gives us the main information about this shape, about message flow, about whole orchestration processing. Send shape with name “OrderAck” means … exactly!
%u00b7 Whenever it is possible use the MessageType of the processed message as a shape name.
%u00b7 Do not repeat the type of shape icon by word.
%u00b7 Do not repeat words from external shape name into the internal, nested shape name.
%u00b7 Feel free to use spaces inside the shape names.
%u00b7 Feel free to repeat the shape names.
7.4.2 Rules for specific shapes
Construct, Receive, and Send:
= name of the processed message without “msg_” prefix.
For example, [OrderAck]
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_OrderAck” copy “OrderAck”
Transform:
= “from “ + name of the Source message
For example, [from OrderAck]
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_OrderAck” copy “OrderAck”
Assignment:
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 OrderAck]
Consider this chapter as “out-of-scope”. I placed it here because we discussed the folder names here. The files placement is a separate and wealthy topic. Here are only main considerations.
* If the project is simple, place all files in one project.
* If we want to use some files for references from other projects, place these files in separate project.
* Place artifacts to different projects if these artifacts have different refactoring lifecycle. For example, the Niem standard schemas are never changed then place them to the separate project. The maps are changed more frequently than schemas and we could place schemas and maps to the separate projects.
* Don’t place the technology-specific schemas and maps away from the orchestration they used for. For example, for the SQL port we generate a (technology) schema and usually create the map to transform the original schema to this (technology) schema. Place these schema and map together with orchestration, not into the Schemas/Maps projects.
In the BizTalk project folder add the subfolder the Tests. Use it to the unit tests. Inside the Tests create subfolders: In, Out, TestMessages.
For the BizTalk project with different artifact files you can add the solution folders the Schemas, Orchestrations, and Maps in case you have several schemas, orchestrations, and maps there.
9 Out of scope
Several BizTalk artifacts are out of scope this naming convention:
%u00b7 BRE artifacts: Rule sets, Vocabularies, etc.
%u00b7 BAM artifacts: Activities, Views, BAM Definitions, Tracking Profiles
%u00b7 Parties, Role links
%u00b7 Itineraries from the ESB Toolkit 2.0. I think the ESB Toolkit is a part of BizTalk 2009, because it is delivered in binary format, supported by Microsoft, has a lot of tooling, including Itinerary Designer.
See also
2. URL in Wikipedia [ http://en.wikipedia.org/wiki/URL ].


Appendix
Syntax
<Word> =:
[A-Za-z1-0]*
<CompositeWord> =:
<Word>.<Word>[.<Word>]
<ShortName> :=
<Word>
<CompositeWord>
<{Any}ShortName> =: <ShortName>
[replace {Any} with any term. For example, term Solutioncreatesa<SolutionShortName> term]
<Company> =: <ShortName>
<Domain> =: <ShortName>
<Solution> =:
<Company>.<Domain>.<SolutionShortName>
<ApplicationName> =: <Solution>
<AssemblyName> =: <Project>
<Namespace> =: <Project>
<SolutionsRootFolder> =: c:\Solutions
<SolutionFolder> =:
<SolutionsRootFolder>\<Solution>
<Project> =:
<Solution>.<ProjectShortName>
<ProjectFolder> =:
<SolutionFolder>\<ProjectShortName>
<TargetNamespace> =:
http://<Domain>.<Company>.com/<SolutionShortName>/<ProjectShortName>/<Version>
<Version> =:
<date>
[in YYYY-MM-DD format]
<Port> =:
<Solution>.<PortShortName>
<Map> =:
<SourceSchemaShortName>_to_<DestinationSchemaShortName>[for one-to-one map]
<SourceSchemaShortName1>_and_<SourceSchemaShortName2>_to_<DestinationSchemaShortName>[for two-to-one map]
Instructions
Keep the names of some BizTalk artifacts in the lists, a list per solution. Create, at last, a list of the target namespaces of all schemas. Keeping them in one list forces developers to use naming convention, because inconsistencies in the names are visible inside these lists on the development stage.
1. Create a new name in the list below.
2. Copy it to the name property of the new BizTalk artifact.
Target Namespace List
Port List

Submit a Comment