Baseline Naming Conventions

Naming Conventions

Version: 1.6
Date: 2006-02-07

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

1.3Reference documents

1.4Abbreviations

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:

4 Naming conventions when creating an Integration

4.1Integrations

ZYS{IS}001.<DESC>

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

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>

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>

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

4.3Contracts

ZYS{IS}001[.]A.<DESC>

Examples

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

Example

5.3Sender/receiver channels

<FROM QUEUE MANAGER>.<TO QUEUE MANAGER>[.N]

Example:

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

Example

Service-specific queues

ZYS{IS}001.<DESC>{.IN}|{.OUT}

Example

Example 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

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

5.5MQ Scripts

ZYS{IS}001_<DESC>.mqsc

Example

5.6Clusters

ZYSC00X

Example

Alias queue managers

The naming convention for alias queue managers used to route into clusters is:

ZYS.CLUSTERS.X

Example

Cluster channels

The naming convention for cluster receiver channels:

TO.<Cluster name>.<Queue manager name>

Example

Cluster 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

6.2Broker

BK_<Queue Manager Name>

Example

6.3Message flows

A Message flow implements a Service, and should be named accordingly:

ZYS{IS}001_< DESC>

Note that Message flow file names can’t contain a period.

Example

Message flow projects

Append the literal _Flow to the Message flow project name.

Example

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>

Note that Message set file names can’t contain a period.

Example

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

Message set projects

Append the literal _Msetto the Message set project name.

Example

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.