Naming Conventions
Version: 1.6
Date: 2006-02-07
Document:Baseline Naming Conventions.doc / Date:2006-09-26
Table of contents
1Introduction
1.1General description
1.2Revision History
1.3Reference documents
1.4Abbreviations
2What’s new in this version?
2.1The document is structured according to the Baseline Concept Model
2.2The Integration concept is stringently defined
2.3The Service concept has been introduced
2.4The naming convention for traffic from the Integration Platform to a receiving application is reversed
2.5The .IN and .OUT extensions in queue names have been deprecated
2.6The queue type qualifiers have been deprecated
2.7WMB Message sets are named after a Service, not a Contract
2.8Some artifacts are no longer covered by the naming conventions
3General guidelines
3.1Naming structure
3.2Using delimiters in names
3.3Recommended characters
3.4Case
3.5Brand name in Naming Conventions
3.6Conventions
4Naming conventions when creating an Integration
4.1Integrations
4.2Services
4.3Contracts
5Naming Conventions for WMQ Objects
5.1General guidelines
5.2Queue Managers
5.3Sender/receiver channels
5.4Queues
5.5MQ Scripts
5.6Clusters
6Naming Conventions for WMB objects
6.1Configuration manager
6.2Broker
6.3Message flows
6.4Message Sets
7Naming Conventions for ICS/WBI Express objects
7.1Business Objects
7.2Collaborations
7.3Maps
7.4Relationships and participants
8Document Naming Convention
1 Introduction
1.1General description
This document lays out the naming conventions used in the BaselineIntegration Platform.
1.2Revision History
Version / Date / Description / Author1.0 / - / Created
1.1 / 2005-04 / Added naming conventions for WBI Express & Interchange Server
1.2 / 2005-10-13 / Adapted to Baseline 3.0 / Martin Rydman
1.3 / 2005-11-07 / Added some remarks, and made some changes, regarding delimiter in names.
Added Naming Convention for WMB Configuration Manager / Martin Rydman
1.4 / 2006-02-07 / Added naming convention for MQ scripts / Martin Rydman
1.5 / 2006-02-15 / Changed Acceptance test environment to Quality Assurance Environment / Martin Rydman
1.6 / 2006-09-26 / Replace period (.) with underscore (_) in Configuration manager and Broker names / Martin Rydman
1.3Reference documents
Document name / VersionBaseline Concept Model.doc
1.4Abbreviations
WMB / WebSphere Message BrokerWMQ / WebSphere MQ
ICS / Interchange Server
2 What’s new in this version?
2.1The document is structured according to the Baseline Concept Model
You will find the naming conventions for concepts (such as Integrations, Services, and Contracts) in a separate section, and the various technology-based naming conventions (such as WMQ, WMB, and ICS) in separate sections.
Read more about the concepts in Baseline Concept Model.doc.
2.2The Integration concept is stringently defined
The new definition will encourage objects that lend themselves to being reused, while maintaining the Integration concept as the primary structure. This leads to some new features:
- One Integration may use objects that are part of another Integration. As an example, se next bullet
- When using the Route To Queue functionality, the RTQ flow and associated WMQ objects are now considered parts of a separate Integration, leading to a different naming of those objects (see Queue names in a generalized routing scenario below)
2.3The Service concept has been introduced
This has a few implications on naming conventions for queues and flows. For an example of this, see next section (2.4).
2.4The naming convention for traffic from the Integration Platform to a receiving application is reversed
In previous versions of Baseline, the naming convention stipulated one exit point for a flow, and that the Contract-specific queue was located on the external server:
In this version of Baseline, the Contract-specific alias queue is the one the Consumer (Order Processor) is writing to:
Since more than one exit point is now allowed, the problem of how to name the outbound queues when more than one queue is needed (e.g., routing) is solved. It is also a natural consequence of the new Service concept.
2.5The .IN and .OUT extensions in queue names have been deprecated
This is a natural consequence of the previous items (2.3 and 2.4)
2.6The queue type qualifiers have been deprecated
No distinction in the queue name is made between local, alias and remote queues.
2.7WMB Message sets are named after a Service, not a Contract
A Message format is now a property of a Service, and since the WMB Message set implements a Message format, its naming convention has been altered.
2.8Some artifacts are no longer covered by the naming conventions
From experience, it has been proved impractical to impose naming conventions for the following artifacts:
- PoD’s
- Message Types
3 General guidelines
3.1Naming structure
Baseline aims at collecting and structuring all objects (documents, queues, message flows etc.) within an Integration. Three major concepts constitute the backbone of the naming structure:
Read more about these(and other) concepts in Baseline Concept Model.doc.
3.2Using delimiters in names
Baseline recommends period (.) as delimiter in all names. Some objects (like some WMB-files) won’t allow a period in their name. In those cases, use an underscore (_).
3.3Recommended characters
Names should contain letters, numbers, and a delimiter, such as period (.). Spaces and special characters (e.g., %, -, /, \) are not recommended.
3.4Case
Conceptual names (Integrations, Services, and Contracts) should be on the form PurchaseOrder, sometimes referred to as UpperCamelCase. This means that each separate word in a name begins with a capitalized letter. All other letters are lower case (except for abbreviations, such as XML).
3.5Brand name in Naming Conventions
In this document you will see ZYS being used for brand name and three digits being used for sequence number. Feel free to adapt the length of the parts to suit specific needs. You can also append some grouping indicator to the brand name. For example, ZYS.ABC could group together allIntegrations in the ABC project within the ZYS organization.
Since the decisions made regarding brand name and serial number will trickle down to MQ objects (such as queue managers and channels), the combined length of the two should not be greater than 7 characters.
3.6Conventions
In this document, some typographic conventions apply:
<DESC> / > denotes text that should be substituted with relevant content[.] / [] denotes an optional element
{.} / {} denotes a deprecated element
X|Y / Choose one (X or Y)
4 Naming conventions when creating an Integration
4.1Integrations
ZYS{IS}001.<DESC>
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration
.<DESC> / Description of the Integration
ZYS{IS}001 is the Integration ID, which is the base for the naming of all other entities in the Integration.
An Integration (as defined in Baseline Concept Model.doc) should concern itself with one data type. This data type should be reflected in the description part of the Integration name.
Examples
ZYS001.Order / Contains all Contracts and Services that concerns an Order. This is an example of a business-oriented Integration.ZYS099.Mail / Contains all Contracts and Services that concerns the sending of Mail notifications. This is an example of an infrastructure oriented Integration.
When deciding a high-level name for an Integration, it might bea good idea to consider the fact that within a large enterprise, several kinds of Orders or Customers might exist. Therefore, a qualified name, such as PurchaseOrder or SalesOrder, might be a better choice.
Baseline considers anything going on in an Integration Platform as part of anIntegration. This means that completely generic Services in the platform, such as a generic router, would be considered part of an Integration handling the data type Message. Such an Integration would probably not get a name containing the data type, but rather a descriptive name of what it does, such as RTQ (RouteTo Queue).
4.2Services
ZYS{IS}001.<DESC>
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration that contains this Service
.<DESC> / Description of the Service
The Service performs an operation on the relevant data type in a particular format[1]. A recommended structure of the <DESC> part is:
<DESC> <verb<format<data type>
<verb> / Should indicate what the Service does<format> / Should indicate in what specific format <data type> is expected
<data type> / Should be the same as the <DESC> part of the Integration name
This naming scheme is by no means mandatoryor exhaustive. Some situations will call for deviations from the scheme (see the SendMail Service below for an example)
Examples
ZYS001.PutXMLOrder / Performs the Put operation on an Order in XML formatZYS099.SendMail / Performs the Send operation on a Mail (note that the <format> part is missing)
4.3Contracts
ZYS{IS}001[.]A.<DESC>
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration that contains this Service
[.]A / Serial letter (A, B, C…). Use double letters (AA, AB, AC…BA, BB, BC…) if many Contracts are required.
Note! The ContractID (ZYS{IS}001[.]A) must be unique within the integration.
.<DESC> / Should be the same as the name of the Service it accesses
Examples
ZYS001A.PutXMLOrder / A Contract that defines how a particular Consumer invokes the PutXMLOrder ServiceZYS099A.SendMail / A Contract that defines how a particular Consumer invokes the SendMail Service
5 Naming Conventions for WMQ Objects
5.1General guidelines
WebSphere MQ names should follow the conventions for WMQ, rather than the standard for object names on each supported platform, as object names may need to be used across platforms.
Don't use lower case letters
WMQ allows both upper and lower case letters in its names.
However, WMQ names are case-sensitive and this may cause errors as some tools convert strings to upper case.
Don't use % in names
This character is valid in all WMQ names.However, it is not commonly used in other names across platforms.
Choose meaningful names, within the constraints of the conventions
The Service and Contract naming conventions should always be the primary source of WMQ names (as outlined in Queues below). In cases where this is not feasible, meaningful names should be used.
Always include a Description
All objects have a DESCR attribute for this purpose. WMQ takes no action on the value, but allows it to be viewed.
5.2Queue Managers
The Queue Manager Name should be max 8 characters
ZYS001D|T|Q
ZYS / Brand Name Zystems001 / Serial Number for the Queue Manager
D|T|Q / Environment
D = Development Environment
T = Test Environment
Q = Quality Assurance (QA)Environment
If this is excluded it denotes the Production Environment.
Example
ZYS002D / QueueManager at Zystems(ZYS). Serial Number 2 (002) in Development Environment (D)ZYS001T / QueueManager at Zystems(ZYS). Serial Number 1 (001) in Test Environment (T)
ZYS003Q / QueueManager at Zystems(ZYS). Serial Number 3 (003) in QA Environment (Q)
ZYS004 / QueueManager at Zystems(ZYS). Serial Number 4 (004) in Production Environment
5.3Sender/receiver channels
<FROM QUEUE MANAGER>.<TO QUEUE MANAGER>[.N]
<From Queue Manager> / The Sending Queue Manager. / Separator Between sending Queue Manager and receiving Queue Manager
<To Queue Manager> / The receiving Queue Manager
[.N] / Serial Number if there is more than one Channel between two Queue Managers
Example:
ZYS001T.ZYS002T / Channel sending information from Queue Manager ZYS001T to Queue Manager ZYS002T.ZYS002T.ZYS003T.1 / The second channel sending information from Queue Manager ZYS002T to the Message Broker Queue Manager ZYS003T.
5.4Queues
Local, Remote, and Alias queues
The name of Local, Remote, and Alias queues should be max 48 characters. The first 15 characters of the queue name should be unique within the queue manager.
No distinction is made between these queue types. The reason for this is that switching from one set-up to another (e.g., when moving from a non-clustered to a clustered environment) often entails changing queue types. If no queue type qualifiers are used, all queue names can stay the same in the new set-up.
Capitalizing WMQ names
Since WMQ objects should be capitalized, the UpperCamelCase names (e.g. PurchaseOrder) must be capitalized. The recommendation is to insert a period (.) between the different words: PURCHASE.ORDER.
Contract-specific queues
ZYS{IS}001[.]A[.<DESC>]
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration that contains this Service
[.]A / Serial letter (A, B, C…)
[.<DESC>] / Should be the same as the name of the Contract (capitalized)
Example
ZYS001A.PUT.XML.ORDER / A Contract-specific queue for the ZYS001A.PutXMLOrder ContractService-specific queues
ZYS{IS}001.<DESC>{.IN}|{.OUT}
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration that contains this Service
.<DESC> / Should be the same as the name of the Service (capitalized)
{.IN} / Denotes a queue feeding messages to a Message flow. Deprecated.
{.OUT} / Denotes a queue receiving messages from a Message flow. Deprecated. Not applicable if the new Service concept is used.
Example
ZYS001.PUT.XML.ORDER / A Service-specific queue for the ZYS001.PutXMLOrder ServiceExample scenarios
All examples below assume atypical clustered scenario, where alias queues are used to route messages to/from the Integration platform. If a non-clustered scenario is used, alias queues in the examples can be substituted with remote queues.
Queue names derived from Services and Contracts
Baseline considers all message exchanges (on a conceptual level) to involve a ServiceConsumer and a Service Provider:
In the picture above, two Consumers access the same Service (ZYS001.PutXMLOrder) via two Contracts (ZYS001A.PutXMLOrder and ZYS001B.PutXMLOrder). The Service’s Endpoint (a local queue) is named as the Service. Following the general WMQ guidelines above, the queue name is capitalized, and the period delimiter is inserted to separate the different parts of the Service description.
Likewise, the Contract-specific alias queues get their names from the Contract names (capitalized and with the different parts delimited with a period).
Looking at the traffic from the Integration platform to a receiving application, we have full symmetry:
Here, the Order Processor is now considered a Consumer, accessing the ZYS001.PutOAGISOrder Service through its own Contract (ZYS001C.PutOagisOrder).
Queue names in a generalized routing scenario
Consider a scenario where Application A (e.g., an ERP system) has a generic channel to the Integration platform, i.e. it will send any data type (Orders, Customer etc) to the same Endpoint in the Integration platform:
In this case, note how Application X is directly involved only in the ZYS999.RTQ Integration using a Contract named accordingly. The Routing Service, in turn, will partake in two other Integrations (ZYS001.Order and ZYS002.Customer).
Queue names in a request-reply scenario
In this case the Price Processor Servicemight inspect a Reply To Queue property of the request message and put the reply on the local Contract queue on Server A.
Queue names in a point-to-point scenario
In cases where the sole purpose of an Integration is to transfer a file from one application to another, the Service name (and consequently the ServiceEndpoint name) may only contain the data type, omitting an operation name:
Dead Letter Queue
The name of all dead letter queues should be:
SYSTEM.DEAD.LETTER.QUEUE
Exception and Back-out Queue
The default name for theIntegration platform general back-out queue is:
BASELINE.BACKOUT
For Integration/application specific exception queues the literal BACKOUT should be appended to the queue name.
Example
ZYS001.PUT.XML.ORDER.BACKOUT / A Service-specific backout queue for the ZYS001.PutXMLOrder Service
Transmission Queue
The transmission queue should follow the name of the channel. The name should equal the last part of the Channel: <To Queue Manager>[.N]
Example
Channel / Transmission QueueZYS001T.ZYS002T / ZYS002T
ZYS001.ZYS006 / ZYS006
ZYS001.ZYS006.1 / ZYS006.1
5.5MQ Scripts
ZYS{IS}001_<DESC>.mqsc
ZYS / Brand Name Zystems{IS}001 / Serial number of the Integration that contains this Service
.<DESC> / Should be the same as the name of the Contract (capitalized)
Example
ZYS001_Order.mqsc / Contains all MQ objects specific to the ZYS001_Order Integration for a particular Queue Manager5.6Clusters
ZYSC00X
ZYS / Brand Name ZystemsC / Denotes a cluster
00 / Serial Number for the cluster
X / Environment
D = Development Environment
T = Test Environment
Q = Quality Assurance (QA) Environment
If this is excluded it equals the Production Environment.
Example
ZYSC001T / The first cluster in the test environmentAlias queue managers
The naming convention for alias queue managers used to route into clusters is:
ZYS.CLUSTERS.X
ZYS.CLUSTERS / Alias queue manager prefixX / Environment
D = Development Environment
T = Test Environment
Q = Quality Assurance (QA) Environment
If this is excluded it equals the Production Environment.
Example
ZYS.CLUSTERS.T / Routes to all test clustersCluster channels
The naming convention for cluster receiver channels:
TO.<Cluster name>.<Queue manager name>
Example
TO.ZYSC001.ZYS012 / The cluster receiver channel on the QM ZYS012 for the cluster ZYSC001Cluster sender channels must be named as the receiver counter-part.
6 Naming Conventions for WMB objects
6.1Configuration manager
In WMB 6.0, the Configuration Manager is given a name. It is not applicable in earlier versions.
CM._<Queue Manager Name>
Example
CM_ZYS001T / Configuration Manager in test EnvironmentCM_ZYS001 / Configuration Manager in production Environment
6.2Broker
BK_<Queue Manager Name>
Example
BK_ZYS001T / Broker in test EnvironmentBK_ZYS001 / Broker in production Environment
6.3Message flows
A Message flow implements a Service, and should be named accordingly:
ZYS{IS}001_< DESC>
ZYS / Brand Name Zystems{IS}001 / The identity of the Integration
_<DESC> / Same as the Service name
Note that Message flow file names can’t contain a period.
Example
ZYSIS001_PutXMLOrder.esqlZYSIS001_PutXMLOrder.msgflow / Message flow files implementing the ZYSIS001.PutXMLOrder Service
Message flow projects
Append the literal _Flow to the Message flow project name.
Example
ZYSIS001_PutXMLOrder_Flow / A Message flow project that contains the flow that implement the ZYSIS001.PutXMLOrder Service.6.4Message Sets
A Message set implements a Message (which is a property of a Service), and should be named accordingly:
ZYS{IS}001_< DESC>
ZYS / Brand Name Zystems{IS}001 / The identity of the Integration
_<DESC> / Same as the Service name, without the verb
Note that Message set file names can’t contain a period.
Example
ZYS001_XMLOrder / A Message set that implements the Message of the ZYS001.<verb>XMLOrder Service(s)Completely generic Message sets that implement industry standards, such as EDIFACT or SWIFT, should not be named according to a specific integration. These are truly reusable artifacts, and should be named after the industry standard and data type they implement.
Example
EDIFACT.D97A.ORDERS / A Message set that implements the EDIFACT D97A ORDERS messageMessage set projects
Append the literal _Msetto the Message set project name.
Example
ZYSIS001_XMLOrder_Mset / A Message set project containing the Message set that implements the Message format of the ZYS001.<verb>XMLOrder Service(s)7 Naming Conventions for ICS/WBI Express objects
The following naming convention is recommended to be used for WebSphere Business Integration Express and Interchange Server. It is based on the IBM WebSphere Interchange Naming components document and adapted to Baseline guidelines.