Jira and JSM naming convention: the BleuLemon method

Here are our best practices, and above all the naming convention for Jira and Jira Service Management (which you will almost certainly recognise on your own instance) applied by every one of our consultants.

1. What is a Jira/JSM naming convention, and why does it matter so much?

Why this question concerns every Jira profile

Whether you are a project manager, a consultant, a developer or an administrator of a solution such as Jira or Jira Service Management, you have all had to pick up a colleague's work at some point, to look at it, correct it or build on it. You know how hard it is to take over work you did not start yourself, and how much time you can lose getting inside someone else's logic, a logic that is not your own. And that is before we even talk about how maintainable the instance is ...

And if one very small change could save you precious time, would you be willing to put it in place?

What BleuLemon does in practice

At BleuLemon, we work to standardise our practices, our way of working and above all the way we configure the tools, so that every Yuzu can pick up the baton quickly and give our client the help they have asked for, whether that means correcting or evolving the configuration of an instance. To that end, we have established a naming convention that all Yuzus apply on every client engagement. Every new Yuzu is introduced to this naming convention and trained in it, much to the delight of our lemony community

The benefits of a clear, standardised naming convention

This naming convention gives us a shared language and, above all, saves precious time on a client engagement, whether it is a new one or one where we are taking over from a colleague.

A clear naming convention lets you:

• Share a common way of working, whether there is one administrator or several.

• Make it easier for our clients to build their own skills once we have left, so that real habits take hold.

• Plan ahead for instances being taken over by other administrators: think of the colleagues who will pick up the baton after you, you are sparing them hours of head-scratching!

• Keep complex projects going over the long term: it guarantees a certain level of maintainability for administrators.

With or without a naming convention

A naming convention reduces errors, audit time and reporting noise, while improving maintainability and governance.

Here, in outline, is the gap in performance and in risk between an instance with no naming convention and an instance aligned with the BleuLemon convention.

Without a convention	With the BleuLemon convention
Atlassian default naming based on simple project keys	Configurations that are easier to read
No standardisation at all	Easier comparison between projects
Difficulty identifying shared items	Shared configuration items easier to identify
Risk of missing potential impacts when making changes	Consistent naming
Difficult onboarding for new administrators	Easier onboarding for new administrators
Longer configuration audits and impact analyses	Configuration audits and impact analyses made easier
Risk of recreating similar items twice	Less risk of overlap between configurations
	Faster creation of new shared projects

2. Primary and secondary schemes: the right Jira logic

The whole configuration structure of Jira and JSM projects rests on schemes, which are attached to the configuration elements that make them up.

For example:

• An issue type scheme is made up of different issue types.

These links matter enormously, because they tell us the configuration order to follow so that these schemes, which are structural for the projects, can be put in place.

There are 2 types of scheme:

• Primary schemes,

• Secondary schemes.

Primary schemes: ITS, FCS, ITSS, WFS, PS

Primary schemes are the Schemes whose configuration is tightly bound to the project and which you will find in every case:

• Issue Type Scheme: This scheme is simple in configuration terms, but it has a restrictive effect on the final configuration of the project. That is true in particular when setting up Request Types on JSM projects, since each Request Type depends on an issue Type from which the whole configuration that follows is derived

• Field Configuration Scheme: The importance of this scheme is underestimated and it is often misused. In most cases it is used to specify:

  • whether a field is mandatory or optional;

  • field descriptions that differ from the one given when the field was first created (this lets you override a field description to fit the project context);

  • in a few cases, on DC, for the more technical among you, altered behaviour through JavaScript injected into the description (so usable in edit mode, but not inline);

  • and rarely, to hide a field (for example a hidden automatic calculation field, and so on). In practice, most of you prefer to rely on whether or not the field is present on a screen.

Issue Type Screen Scheme: This scheme lets you associate, according to the request type, the screens for each operation (Create, View, Edit) with their fields.

Workflows Scheme: This scheme lets you associate, again according to the request type, the Workflow to be used.

Permission Scheme: This scheme is important and must be configured with care, because it is what will allow your users to access the project or not. It is important to configure it with project roles as far as possible, so that you can reuse it across your different projects. This is one of the best practices we recommend to our clients.

How tightly these schemes depend on one another varies with the complexity of your Workflows, through which you will be able to:

• put in place consistency checks on the data entered => Requires plug-ins on Cloud;

• make the secondary paths of your Workflows conditional;

• and much more ...

Secondary schemes: ISS, NS, IPS

Secondary schemes are the Schemes whose configuration can vary more easily from one project to another without calling the Primary Schemes into question. They are not all used systematically in projects. They include:

• Issue Security Scheme: Very rarely used, this scheme is what makes tickets confidential. In very rare implementations, it can be necessary to treat this scheme as Primary, as soon as the need for confidentiality and restricted visibility is present.

• Notification Scheme: The configuration of this scheme is so secondary that it can often be removed from your project configuration, as soon as your users are mature enough to use well-configured Dashboards coupled with the occasional filter subscription. In short, it is for those who are tired of being spammed by Jira. (Yes, they exist!)

• Priority Scheme: It is considered secondary on Jira projects but primary on JSM projects, since the notion of priority is very often used on “Support” type projects.

So you can see here that Secondary Schemes can become Primary depending on your use cases and on the tool.

3. Naming rules: codes, syntax, examples

Careful: the project templates offered natively in Jira and Jira Service Management do not follow these naming conventions. If you create a project from one of these templates, we recommend applying the naming convention to the generated elements straight away.

Every configuration element, and every system, has to follow a naming rule that is explicit, flexible and quick to grasp.

From our experience, we always stick to a few principles:

1. Prefer acronyms and abbreviations of the English terms for Jira configuration elements. Why?

   • Jira is developed in English and the terms have barely changed since the first versions,

   • The French translations of successive versions have often changed completely, and that may well continue,

   • The reference documentation is in English ... You may as well get used to it 😉

2. Try to give different concepts distinct names across projects. Take inspiration from the project management methods and models around you (Scrum, Kanban, ITIL, CMMi ...). For example: as far as possible, an issueType (ticket type) should mean the same thing in every project.

3. Follow a uniform, generalised syntax of the form CodeConfig (ConfigNames) where,

   • CodeConfig is a code (2 to 4 characters) encoding the type of configuration element concerned ...

   • ConfigNames is an open list of more or less distinctive names relating to the configuration element.

Naming rules for concepts

Codes	Concepts	Naming
ProjectModel	Project model	A functional name, explicit in as few words as possible.
IssueType	Ticket type	A functional name, explicit and distinctive enough
Operation	Operation	An operation with a screen configuration of its own. English terms preferred: Create, Edit and View, or even Any where they are identical.
Transition	Workflow transition	Generally, these will be verbs.

Naming rules for configuration elements

Scheme: Issue Type

Codes	Naming pattern	Examples
ITS for Issue Type Scheme	Min: ITS (ProjectType) ITS (ProjectKey)	ITS (Customer Support) ITS (Internal Application) ITS (Scrum) ITS (Kanban)
	Max: ITS (ProjectType) ITS (ProjectKey)	ITS (SUP) (which corresponds to the project key SUP)

Notes: Even where several project typologies include the same ticket types, it is preferable to create an Issue Type Scheme specific to each typology, or even to each project.

Scheme: Field

Codes	Naming pattern	Examples
FC for Field Configuration	Min: FC (IssueType)	FC (Support Request) FC (Anomaly) FC (Problem) FC (Incident) FC (Bug) FC (Enhancement) FC (User Story) FC (Defect)
	Max: FC (ProjectType, IssueType) FC (ProjectKey, IssueType)	FC (SUP, Hardware Incident)

Notes: A Field Configuration can be thought of as a data schema. That is, it lets you specify an exhaustive list of the fields involved in handling a ticket type (issueType).

Codes	Naming pattern	Examples
FCS for Field Configuration Scheme	Min: FCS (ProjectType)	FCS (Customer Support) FCS (Internal Application) FCS (Scrum)
	Max: FCS (ProjectType) FCS (ProjectKey)	FCS(SUP)

Notes: The sole purpose of the Field Configuration Scheme is to associate Issue Types and Field Configurations.

Codes	Naming pattern	Examples
CS for Configuration Scheme	Min: CS (ProjectType,FieldName) CS (ProjectKey,FieldName)	CS (Customer Support, Platforms)

Notes: The Configuration Scheme applies to a field and defines the context in which it is used (for such and such projects and/or ticket types, and so on)

Scheme: Screen

Codes	Naming pattern	Examples
OS for Operation Screen	Min: OS (IssueType, Operation)	OS (Support Request, Create) OS (Support Request,View) OS (Support Request,Edit) OS (Task,Any)
	Max: OS (ProjectType, IssueType, Operation) OS (ProjectKey, IssueType, Operation)	OS (Task,All) OS (Scrum, User Story, Edit)

Codes	Naming pattern	Examples
TS for Transition Screen	Min: TS (Transition) Max: TS (ProjectModel, IssueType,Transition)	TS (Start) TS (Deliver) TS (Suspend) TS (Assign) TS (Bug, Assign) TS (Application, Enhancement,Deliver)

Codes	Naming pattern	Examples
SS for Screen Scheme	Min: SS (IssueType)	SS (Support Request)

Codes	Naming pattern	Examples
ITSS for Issue Type Screen Scheme	Min: ITSS (ProjectType) ITSS (ProjectKey)	ITSS (Support)

Scheme: Workflow

Codes	Naming pattern	Examples
WF for Workflow	Min: WF (ProjectType,IssueType) WF (ProjectKey,IssueType)	WF (Support Request)

Codes	Naming pattern	Examples
WFS for Workflow Scheme	Min: WFS (ProjectType) WFS (ProjectKey)	WFS (Support)

Scheme: Permission

Codes	Naming pattern	Examples
PS for Permission Scheme	Min: PS (ProjectType) Max: PS (ProjectType,ProjectName) PS (ProjectKey,ProjectName)	PS (Support)

Scheme: Security

Codes	Naming pattern	Examples
ISS for Issue Security Scheme	Min: ISS (ProjectType) Max: ISS (ProjectType,ProjectName) ISS (ProjectKey,ProjectName)	ISS (Support)

Scheme: Notification

Codes	Naming pattern	Examples
NS for Notification Scheme	Min: NS (ProjectType) Max: NS (ProjectType,ProjectName) NS (ProjectKey,ProjectName)	NS (Support)

Scheme: Priority

Codes	Naming pattern	Examples
IPS for (Issue) Priority Scheme	Min: IPS (ProjectType) Max: IPS (ProjectType,ProjectName) IPS (ProjectKey,ProjectName)	IPS (Support)

Notes: Since Secondary Schemes are not very structural and may need to be adapted to a specific project, the Project name can be included in the naming.

4. Automation: conventions, recipes and governance

Automation rules in Jira and JSM can be:

• Global: shared across all the projects on the JSM and/or JIRA instance

• Shared across several projects: you simply state which projects the automation applies to

• Shared across a project type: you simply select the project type concerned

• Single: for one project only, these are local rules specific to the project.

In every case, our advice is:

• Name your automation properly;

• Explain in the description what the automation does, and even the context in which it applies and is used;

• Always set “Automation For Jira” as the actor for execution (to avoid automations failing if you use another user account that may be deactivated when that person leaves the company).

There is also a naming convention for automations, which we share with you below:

Type of automation	Naming pattern	Examples	Notes
Global automation	ALL - Rule name	ALL - Auto-close a ticket after 10 days
Automation shared across several projects	PROJECTS KEY - Rule name	SUP, MVT, DVP - Priority calculation	State clearly in the description which projects the rule refers to.
Automation shared across a project type	PROJECT TYPE - Rule name	Support projects - D+7 reminder Awaiting client reply	State clearly in the description which type of projects the rule refers to.
Single or local automation	PROJECT KEY - Rule name	SUP - Automatic assignment to L1 SUP-Sync SNOW - Comment sync SUP-Sync SNOW - Group	These automations can also be used as part of an interface with third-party tools. In that case, remember to include the name of the third-party tool being synchronised in the description and in the rule name.

Minimum governance

• Owner required: name the owner of the rule (a person, since a team cannot be an owner)

• Version: (e.g. v2) as a suffix to the name if the logic changes

• Changelog: 1 line in the description at each significant change (date, author, change)

• Periodic review: quarterly (tests, project scope, potential collisions)

• Execution actor: “Automation for Jira”

In the end ...

• Whether you follow the BleuLemon convention as it stands or not, the main thing is to have one convention, shared by everyone.

• Do not hesitate to question that convention as time goes on.

• If you use standard templates (Jira BluePrint), remember to rename the generated elements to match the convention in place.

Frequently asked questions (FAQ)

Having identical Issue Types: sensible or absurd?

• Definition: An Issue Type Scheme defines the list of Issue Types, but not only that.

• What to do:

  • In the absence of a configuration element representing the notion of Project Type, the Issue Type Scheme is the best candidate to formalise it. So we allow ourselves to have 2 Issue Type Schemes holding the same Issue Types, because they differ by their name, and that name carries information.

How should Create/Edit/View screens and Transition Screens be named and structured?

• Definition:

  • Operation Screens (OS) carry the Create/Edit/View operations;

  • Transition Screens (TS) relate to workflows.

What to do:

• Use English for the operations and “Any” where they are identical (e.g. OS (Task, Any));

• Name TS with verbs (e.g. TS (Start), TS (Assign)).

When should you create one Workflow per issue type rather than a single workflow?

• Definition: a dedicated workflow per issue type clarifies transitions and screens and reduces ambiguity.

• What to do: Put off implementing the specifics between Issue Types for as long as possible (clone the workflow when you start on the part specific to an Issue Type )

Request Types vs Issue Types (JSM): how do you map them correctly?

• Definition: in JSM, Request Types ≠ Issue Types.

• What to do: Document the mapping explicitly in the screen schemes (ITSS/SS) and follow the existing naming conventions. Avoid ambiguous labels.

Cloud vs Data Center: what precautions apply to validators, conditions and post‑functions?

• Definition: the naming logic stays the same; the capabilities differ.

• What to do: keep the same patterns (ITS, FCS, ITSS, WFS, PS...) and describe dependencies and effects in the description (in particular for validators, conditions and post‑functions).

BleuLemon supports IT departments through their transformation with freshness and quickness of mind. We help organisations release the collective potential of their teams, opening the way to a stronger and more fulfilling organisation of work.