top of page

Naming convention

Standardizing nomenclature is essential to maintain consistency across all Atlassian product configurations. In any case, despite being a very common practice in IT, many times as Atlassian administrators we fail to give this the necessary priority on the platform. This post is not intended to identify the benefits of doing so, but rather to share our own standard that we apply over and over again in each of the instances we manage for our clients.

Within the content we will find the following sections:

  • General Structure

    • Configuration Item

    • Category

    • Project Template

    • Template Number

    • Destination Status

  • Naming Options

  • Examples

General Structure

Our standard is always based on the following section structure


<Configuration Item>-<Project Category>-<Project Template>-<Template Number>-<Action/Target Status*>


The order will always be the same, what may vary is the number of sections that will depend on the level of configuration granularity that allows what we are configuring. For example, a workflow schema can only be configured at the project level, so the Template Number and Target Status sections would not be relevant.


Naming Options

Here I will break down each of the sections to simplify the understanding of how the name of what we are configuring is formed.


Configuration Item Section

The following table shows the options for this section.

ITSCH

Issue Type Scheme

WRK

Workflow

WRKSCH

Workflow Scheme

SCR

Screen

SCRSCH

Screen Scheme

ITSCRSCH

Issue Type Screen Scheme

CF

Custom Field

FLD

Field Configuration

FLDSCH

Field Scheme

NTFSCH

Notification Scheme

SECSCH

Security Scheme

PERMSCH

Permission Scheme

GRP

Group

APP

Application Configuration Item

Clearly, one can make one's own adjustment regarding this. The important thing is that in this section we provide information on what we are configuring, which has proven to be very useful for users who are starting to manage the tool.


Category Section

In this section of the name we seek to identify how global and massive the use of what we are using is. In general, Jira or Confluence categories are used to group projects that share certain common characteristics and, in many cases, their configuration.

In our case, when defining the name of the category, we use the description section to define the nomenclature of each of them and thus standardize the names to use in this section as can be seen in the image below.

Each category has its nomenclature in its description.

Outside of the options we have in the categories, we will always have an additional option which is ALL which indicates that the configuration can impact projects of any category. In this way, our nomenclatures can have names that begin like WRKSCH-ALL or NTFSCH-ELT.


Project Template Section

As its name indicates, here we will be keeping track of the project to which you apply. In an ideal scenario, this template will have a number instead of having the project ID. Why? Because our goal is always to reuse what we create, if we associate our configuration with project A, we should create a copy of it to use in project B and follow the nomenclature at the same time.

In a similar way to the categories section, here it is valid to use the ALL option that would allow me to indicate that this is used for all projects in a category. In some clients, the categories even had various configurations but every new project had to start with the default configuration of the category, so the DFT option was also added to easily identify which one it was. As you begin to see, as we go deepern into the standard, we begin to have greater flexibility to identify what we are configuring without losing order and understanding the impact.


Template Number Section

By reaching this level of depth, we are entering configurations associated with the types of incidents. Under the same reuse criteria, our options here will only be numbers or the ALL option. Putting the name of the type of incident will only involve duplicating the information if we have to reuse something for more than one issue type, which would not scale and would be extremely difficult to maintain.

Tip: if the numbering of the issue type is one to one between the workflows, the screens and their schemes, you will make administration much easier. Since you will know that workflow 1 will always work fine with screen 1 and there will be no risk of breaking something in a project that could potentially be using a configuration that is not aligned in its numbering.

Particularly, when working with groups, this section is directly associated with the project role, so the nomenclature becomes an abbreviation of the corresponding role, such as ADM, DEV, USR as an example.


Action/Target Status Section

This section is only used at the Screens level since these allow a greater level of flexibility than other items to configure. Hence the valid options are the following

CREATE

Screen for the action of creating incidents

EDIT

Screen for the field editing action

VIEW

Screen for View action

ALL

Screen valid for any action

Destination state name

Applies to screens used during transitions in workflows

GLB#

Global usage Screen

The last option on the list has certain restrictions in order not to abuse this type of screens. This nomenclature is reserved for global use screens, where all other parts of the name are cataloged as ALL and as a general rule, none of these screens should have more than 3 fields. Simply for a logical reason that the more options, the less likely it will actually be used for any issue type of any project on any category.


Examples

Enough theory so far, let's go to practical examples to see the nomenclature in action, just to simplify the examples, I will be grouping them under the type of configurations that accept the different levels of depth


Example

Meaning

WRKSCH-ALL-ALL

Workflow Scheme for all projects in all categories

ITSCH-ELT-1

Issue Type Scheme number 1 for the Elite category (ELT)

NTFSCH-DEV-ALL

Notification scheme for all projects within development category (DEV)

CF-CNF-ALL

Custom Field context for all projects in the confidential category (CNF)

Examples of configurations of field configuration schemes, issue type schemes, workflow schemes, issue type screen schemes, permissions scheme, notification scheme, issue security schemes or custom fields.



Example

Meaning

WRK-CSTM-FIN-1

Workflow 1, of the Fintech project (FIN) of the custom category (CSTM)

SCRSCH-ALL-ALL-3

Screen scheme 3 for all projects in all categories

GRP-CST-BNK-DEV

Developers (DEV) role group for the Bank project within Customer Category (CST)

GRP-CST-ALL-ADM

Administrator (ADM) role group for all projects within Customers Category (CST)

Examples of configurations for field configuration, screen schemes, workflows, custom fields, groups


Example

Meaning

SCR-ALL-ALL-2-ALL

Screen 2 for all actions (create, view and edit), for all projects in all categories

SCR-ALL-ALL-ALL-GLB3

Global usage screen number 3

SCR-SUP-SA-1-CLOSED

CLOSED screen, from template 1 for the Atlassian Support Project (SA), within the Support Category (SUP)

Examples of screen configuration configurations


Bonus

In case you are interested in establishing your own standard and want to know the considerations to take into account when defining them and some of the most common errors when implementing them, I leave you a link to the episode of our podcast that we dedicate to this.

PS: You might need to learn spanish in the middle sorry :)






Do you have a different criterion to implement what is presented? Tell us in the comments

It is very common that there is more than one way to do things with Atlassian tools and we would love to discover other ways to solve them.

We hope you enjoyed reading,


Until the next time.


0 comments

Comments


bottom of page