Home » Blog » EAM Naming conventions for interfaces

EAM Naming conventions for interfaces

The other day we were discussing naming conventions for modelling interfaces in our Enterprise Architecture tool. There is the general question of a naming convention and the specific application of this question in the context of interface naming. Here are some basic thoughts I´d like to share.

1) Why is a naming convention useful?

First of all let me explain why I think you should create a naming convention for your EAM modelling in general. Be it an interface, an application or a business capability – you should be aligned within the company how to name your EAM artifacts.

The reason is that a naming convention will add significant value to your EAM modelling and analysis. An effective naming convention will ensure readability, uniqueness, scalability and provide a high recognition value.

With a naming convention the names in your EAM model will remain readable and easy to understand. Good namings of your objects / artifacts enable architects and decision makers alike to easily identify the object. For example the term „SAP“ does not identify one specific SAP system or even the specific product (SAP ERP? SAP SRM? …). Go for something easy to recognize by the business and IT alike such as „SAP PG1“ or „SAP Procurement“. It depends a bit on the terms already being used in your organization.

Uniqueness is a rather obvious value of a naming convention since it allows you to identify an artifact unambiguously. You will easily confirm that somethink like „Application 1“, „Application 2“, „Application 3“, etc. is rather inappropriate since you cannot distinguish one application from the other. However you should be aware that complete uniqueness will diminish readability and ostensibility. An extreme example would be to list the servers in your EA landscape only with their IP address.

Ostensibility or recognition value is an attribute of your naming convention that enables you to deduce specific information from an artifacts name. Think of adding the transmission direction to an interface name for instance („Customer Master Data Outbound“) or the hardware type to an IT component („NAS Jupiter“).

You want to make sure that this information is not redundant to what your modeling language is already offering. If you model your landscape with Archimate it would be useless to name an interface like „Interface ABC to DEF“ because in Archimate interfaces are already marked with specific symbols. Or take LeanIX for example: to name business capabilities it would be redundant to name them „BC Direct Sales“ and „BC Wholesale Sales“ because LeanIX has a clear symbol for business capabilities.

Last important value that a naming convention is adding is scalability. Scalability means your naming convention lets you add as many EA artifacts as you like without loosing uniqueness, ostensibility or readability. This aspect is a key value and at the same time incredibly difficult to achieve. Scalability contradicts readability and likelihood. The easiest and most scalable naming convention would be consecutive numbering. But this is neither readable nor ostensible. Another bad example would be server hostnames. A lot of companies assign very individual hostnames to their servers (such as „lucifer“, „hemlock“ or „scylla“). While this is readable it does not offer additional information about the servers and thus is not ostensible.

2) What are possible naming conventions for interfaces ?

An interface in Enterprise Architecture Modelling consists at least of the following elements:

  • Interface Provider (or Source)
  • Interface Consumer (or Destination)
  • Data (which is transmitted)
  • Activity (what happens with the transmitted data at the destination)

Those items remain very stable over the interface´s lifecycle. Changing them usually means you create a new interface replacing the old one. Please note that we are talking here about EAM interfaces which are logical constructs. I am aware that changing a technical interface destination not necessarily means to reprogram everything from scratch 😉

Based on these assumptions I see the following options for a naming convention:

1) Source – Destination

The source and target of an interface remain stable throughout the interface´s lifecycle. Usually, when either of those items changes the whole interface is undergoing a major change. Thus creating a naming convention <Source>-<Target> is one possible way.

2) Data or Object

Another item that usually remains stable over a lifecycle are the transmitted objects. Yes, from time to time you add or remove fields. But this level of information is not relevant for EAM anyways. So naming an interface „Customer Master Data“ is a viable option. However it is not a unique one in your landscape if you transmit customer master data in other contexts as well.

Thus adding the Source and/or Destination will add to the uniqueness of your interface naming (but probably not to readability).

3) Data or Object + Activity

While the type of data or the object is usually not unique enough you could add to uniqueness by describing what´s happing at the destination. Sometimes the data is only upload to complete the destination´s database. But oftentimes data is sent through an interface and processed in some way (e.g. merging invoice line items to invoices and creating a PDF file).

4) Data + Destination + Activity

This is actually my recommendation because it will a good compromise of readability, uniquness, scalability and ostensibility. Furthermore it will not overburden or confuse non-technical customers of your EAM department – the business. In bigger landscapes however this recommendation might get to its limitations as well.

3) Some practical advice

Depending on your EAM tool you will surely be able to add more data fields to an interface such as the interface direction (Inbound, Outbound, Bidirectional), transmission type (synchronous, asynchronous), provider information or the technical platform. However I would not recommend one of those to add to the naming convention. This will make things even more complicated because some of these elements tend to change over the interface´s lifecycle.

Also I would refrain from extreme „coding“ and abbreviations. You might end up with an interface naming convention that only its creator may understand completely. A really bad example is „A12-Ext-CustMasDat-Out-SF“ for indicating a self-programmed EDI-Interface which is hosted by an external provider and sends customer master data out to Salesforce. This will not help to align IT and business for sure.

Another hint I´d like to share: sometimes it makes sense to just use an item´s „traditional“ name, i.e. use the name that everybody recognizes because it´s been always named this way. So if your interface´s name is „Hans“ and everybody knows what Hans means – then you may go for it. However this will likely find it´s end in bigger, global organizations because it requires a specific kind of locality.