Application Naming Convention

[saschawildg]

Any naming or category system will turn out to be insufficient at some point in time. Yet, no naming convention is even worse – so teams are well-advised to agree on a naming convention early on – and once its deficiency is obvious, adapt and refactor. Names are not just identifiers, they also expose culture, tradition and mental models – hence defining and agreeing on a naming convention is inherently difficult.

The following proposal should be seen as a starting point for discussion. It is not the single source of truth and should not be considered as prescriptive guidance without conversation and review. An application naming convention should cover 3 items:

1. Application display names

2. Scoped application scope names

3. Global application technical prefixes

The application display name is the user-visible name of an application – it applies to both scoped and global applications.

The scoped application scope name – as the name suggests – is only relevant for scoped applications. The scope name is used as a prefix for technical table names, as a namespace identifier when calling functions or classes in Script Includes from outside the scoped application and various other places. The scope name of custom applications by default starts with “x_” followed by a customer specific identifier, another underscore and then a developer-provided postfix. The total length of the scope name (including the leading “x_” and company identifier) must not exceed 18 characters – which requires the use of abbreviations. Note that the current version of ServiceNow Studio does not even allow to edit the scope name during application creation – which requires the scope name to be modified using a script after creation.

The global application technical prefix is not a technical feature of the platform – it is a recommendation. The technical prefix should be used e.g. for Script Include names – and hence should be useable as a JavaScript object name prefix (i.e. should only contain capital and lowercase letters, must not start with numbers and should not contain special characters). This is to avoid name clashes with other application files in the global scope.

The following patterns are proposed here:

Application display names

“<Company>[ <Project>][ <Process>][ <Type>][ <Context>][ Global]”

• <Company> - The name of the customer
• <Project> - Optional identifier of a customer has multiple, independent instance stacks for different organizational units or use cases
• <Process> - the name of the process (or business capability)
• <Type> - The type identifier
  • “Platform” – Platform apps (see chapter “Application Architecture and Dependency Management”)
  • “UI” – User Interfaces
  • “INT” – Integrations to external systems (inbound and outbound) – but ideally not both in one app
  • “Core” – Contains components to be used by other applications
  • “” – No type identifier indicates an application that implements a process (or business capability)
• <Context> - Used for “UI” and “INT” applications to specify exactly which user interface or integration is implemented in this application
• <Global> - is a postfix to mark global applications

Scoped application scope names
“x_<company abbreviation>[_<project abbreviation>][_<process abbreviation>]_<type>[_<context abbreviation>]”

• <company_abbreviation> - 2-4 letter abbreviation of the customer name – defined by ServiceNow
• <project abbreviation> - Optional 2-3 letter abbreviation of the project identifier
• <process abbreviation> - Optional 3-4 letter abbreviation of the process (or business capability) name
• <type> - Same as for the application display name (but in lowercase letters)
• <context abbreviation> - Option abbreviation of the context name using whatever space is left within the 18 characters constraint

Examples

• “ACME Incident Management” / “x_acme_inc”
  ACME’s scoped app that defines customizations to the Incident Management Process.
  The fictious ACME company in this example does not distinguish between different projects.
  “Incident Management” is the process name, abbreviated by “inc”.
  For processes the type and context is blank.
• “ACME Incident Management Global”
  This global application acts as a sidekick to “ACME Incident Management” which contains additional records related to the Incident Management process which for whatever reasons must be in the global scope.
• “ACME UI Service Portal” / “x_acme_ui_sp”
  ACME’s scoped app for Service Portal customizations.
  This fictious Service Portal covers many processes and is hence not process specific, so the process part is blank.
  The type is “UI”, the context is “Service Portal”.
• “ACME UI Service Portal Global”
  This global application acts as a sidekick to “ACME UI Service Portal” which contains additional records related to the Service Portal which for whatever reasons must be in the global scope.
• “ACME INT Jira” / “x_acme_int_jira”
  This scoped application contains the integration with ACME’s Jira instance.
  Hence the type is “INT”. “Jira” is the context and is short enough so that no abbreviation is required.
• “ACME ITSM Core” / “x_acme_itsm_core”
  “ITSM” is a “Process Group” and the type is “Core” – such applications contain data model extensions, ACLs and roles related to multiple processes.
• “ACME Core” / “x_acme_core”
  This process independent scoped app contains reusable code and capabilities that may be used by all other applications. The type “Core” indicates that the app contains components to be used by other applications – including data model extensions and roles.
• “ACME Platform” / “x_acme_platform”
  ACME’s highlander platform application – that depends directly or indirectly on all other applications and hence acts as a release manifest.
  the platform app also contains the persona roles and sets platform-wide configuration settings.

Global application technical prefixes
“<Prefix>”

• <Prefix> - The prefix should be a shorter variant of the application name (but only consists of letters and numbers, but must start with a letter) – With this constraint it can be made part of JavaScript object names and is compatible with Script Include names which either represent the class or function they contain

Examples

• “AcmeIncMan”
  The prefix for the “ACME Incident Management Global” application, which is the sidekick of the scoped “ACME Incident Management” application.
  E.g. a possible Script Include function could be named “AcmeIncManIdentifyAssignmentGroup()”
• “AcmeITSMCore”
  The prefix for the “ACME Core Global” application, which is the sidekick for the scoped “ACME Core” application.
  E.g. a possible Script Include function could be named “AcmeITSMCoreGetTasksByConfigItem()”

Read the full story:

https://www.wildgrube.com/download/A%20mature%20Development%20and%20Deployment%20Process.pdf