Naming convention for Pigment

Naming conventions improve clarity and functionality at every level, helping everyone using your Workspace. This article introduces the naming conventions used in our templates and customer Workspaces at the Application, Folder, Block, Board, and View levels.

Why use a naming convention

When you start typing the name of a Block into the formula bar, a dropdown provides a list of Blocks featuring the typed letters. For example, if you need the “Salary” Metric for existing employees, you may not know from the list which “Salary” Metric is for existing employees and which is for TBH (to be hired).

Choosing the wrong Metric could create significant errors now or further down the dependency tree if left unchecked. When you’re in the middle of modeling, it can be challenging to double-check or take extra time. This is why naming conventions in your Pigment workspace are crucial.

Why Names are Important in Pigment

Pigment orders items in ascending alphanumeric order (0-9 followed by A-Z) with special characters coming first. This impacts how easy it is to navigate the Workspace, find what you are looking for, and understand the logic behind. This is true both for referencing Blocks in formulas and for following defined processes and logic flows across multiple Blocks or Applications.

Clear naming conventions help document your model, visualize Block interactions, onboard new users quickly, improve maintainability and facilitate collaboration with the Pigment Support and Professional Services team.

Defining and documenting your naming convention

A naming convention is only useful if it is memorable and intuitive for your team. Document your naming system so that new and existing modelers can easily learn it. We recommend displaying the naming convention you choose to adopt in an “Application Guide” Board created in each Application. This Board also explains the purpose of the Application, the roles involved and their actions, color conventions, and any helpful definitions.

How to name Applications

The Application naming convention is quite simple and usually revolves around the goal of arranging your Applications in the desired order within your Workspace. We usually do so by using a two-digit number prefix and a descriptive Application title. Keeping the “0” (example: “01.” instead of “1.”) supports having more than nine Applications and avoids wrong ordering such as: “1.” , “11.” , “12.” , “2”.

Below are some typical Applications for Pigment and how to name them:

• Hub: Contains shared Dimensions, Calendar, exchange rates, security administration, and any general settings used in more than one Application in the Workspace. We recommend having the Hub as the first application displayed in the Workspace to facilitate access by using a 00 prefix.
  
  Example: 00. Hub
  

• Use Case-Specific Applications: Applications dedicated to a business process involving specific roles. We recommend a numbering that reflects a logical order between these business processes.

  
  Examples: 01. Core Reporting, 02. Workforce Planning, 03. Opex Planning, 04. Topline Planning
  

• Unused Applications: Applications not currently used but that you want to keep in the Workspace can be prefixed with “ZZ_” to move them to the end of the display order. Remember to regularly clean your Workspace by deleting unused Applications.
  

  Example: ZZ_POC Revenue Planning
  

• Training or Testing Applications: Add the purpose to the end of the title. Once this Application has served its purpose, it should be immediately deleted.
  

  Example: 04. Topline Planning - Training

ℹ️ Note

For more insights on how to organise your Workspace through multi-Application architecture, see Multi App Architecture: Why & How?.

How to name folders

Folder naming is similar to Application naming, helping you order items within your Workspace and making it easy to identify what they contain without having to open them.

Unlike Applications, where the number is relatively small and easy to name appropriately, folders can come by the dozens with different depths when leveraging subfolders. The folder structure and naming used can be considered the backbone of the model structure and is usually the first element to document.

We address this by using once again a two-digit number prefix starting at “00.” or “01.” and restart at “00.” or “01.” at every folder layer, following a logical order aligned with the business process and calculations.

Example:

In this structure, you can clearly see the types of Blocks within each folder. They’re arranged in an intuitive order according to the process and model structure, making it easier for your users to find what they need based on the action they wish to perform or the data they wish to find.

ℹ️ Note

For more insights on how to organise your folders you can read this article.

How to name Blocks

The naming of Blocks is by far the most important naming in Pigment as Blocks’ names are referenced in formulas. Good naming makes formulas easy to write and to understand. So far, the naming conventions for different types of items have been very similar, and Boards are also largely the same. However, for Blocks, it’s important to be more nuanced in your naming to avoid confusion.

Our goal is to give a simple, explicit name that gives as many indications as possible on the purpose or role of the Block we are creating in the Application. We can also provide insights on the origin of the data or specific business processes involved by adding prefixes or suffixes directly in the name.

⚠️ Important

Dimensions need to be named simply and concisely, as they’re displayed as-is in the whole model, including in your Boards. This means we are unlikely to use numbers or prefixes unless it’s clearer for the modeler and end-user.

The general principle we choose to use is to leverage two type of prefixes:

• Prefix A: indicating the Block role or position in the business process: for example, the Block is used in the specific process of forecasting Revenue.

• Prefix B: indicating the Block utilisation. How is the Block used in the model? Is it used to import data, is it used to input assumptions, or is it used to display a final result?

By combining these two prefixes, we can understand at-a-glance a Block’s role and usage in a model.

ℹ️ Note

We recommend using capital letters for prefixes to easily distinguish them from the Block name and also using the underscore “_” when combining them to easily spot the separation.

Example: Metric used to input a Revenue growth %

• Prefix A:

The prefix A options will depend on the business process covered by the Application. A simple way to proceed is to follow the folder structure by using a prefix corresponding to an acronym of the folder/sub-folder name. You can also choose to use the folder/sub-folder numbers as prefix. In this case, you should open the quote mark in the formula bar or Pigment will consider that you’re typing numbers not names.

Here are some prefixes we often use:

Of course, you should add your own prefixes to this list depending on the specifics of your Application. You can also combine multiple Prefix A options to provide more detail on a Block’s role and position within the Application.

Example:

REV_PLAN_: for Blocks used in the Revenue planning part of the model

REV_ACT_: for Blocks used in the Revenue actuals part of the model

• Prefix B:

The Prefix B list is quite consistent across different models. Below is a non-exhaustive list of defined prefixes that we suggest adopting. Be open to adding new ones as business processes and use cases demand. These prefixes can also be used as suffixes or even combined together (e.g. “Asm_Input_Churn rate (%)” for a Metric used to input the churn rate assumption). Ensure consistency in how you combine them and that the ordering makes sense for your team and use case.

Here are the prefixes we most frequently use:

ℹ️ Note

• If a specific order to the calculation needs to be retained to understand the flow, add a number to the name, e.g. MCM_CALC_01_.

• Using “(#)”, “($)” or any other symbol or abbreviation can be helpful to provide more information about the Metric’s use or purpose and the type of data it holds.

• When creating Metrics to test calculations of changes, always use a “-TEST” suffix to enable quick filtering of all test Metrics. They should ideally not stay as-is in the model, and should either replace old Metrics (which can be kept with an “-OLD” suffix) or should be deleted.

Here is an another example of a Metric name:

As you can see from this example, all we have to do is read the name of the Metric to gain valuable insights into its role and purpose and how it should be used in the model.

You can change the ordering of the prefixes/suffixes if you prefer a different logic; what’s important is to keep a consistent, logical approach to naming at the level of complexity that is most appropriate for your model.

Here are more examples of Block names:

• PUSH_PR_New Business Revenue ($): Metric with new business revenue data that is shared from the Revenue Application to be used in a different Application

• ADM_MAP_Month to Ramp-up Month: Mapping Metric located in the “00. Admin” folder that is used to translate Ramp-up Month back to the Month Dimension

• LOAD_EE_Employee Data_HRIS: Transaction List used to load the existing employee data from an external HRIS system

• ASM_INPUT_Merit Tenure: assumption Metric used to input the minimum tenure for the merit increase

• SC_ASM_INPUT_Sales Quota ($): sales capacity Metric used to input assumptions on Sales Quota

• ARM_READ_Cost Center x County: Metric used to apply “read” Access Rights restrictions to allow end-users to see data only in specific Cost Center and/or Country

• [TBL] EXP_Cost Center billing (€): Table used to export data for billing purposes

A quick note on referencing Blocks:

• When referencing Blocks in Pigment formulas, typing an empty space indicates two separate objects. If you type the name without the space, Pigment surfaces Metrics with a space as well. We don’t recommend using periods (.) or colons (:) in your Block names because it breaks the referencing.

• Remember that you can also use square brackets in your Block naming conventions to make the Blocks appear at the top of the folder. But again, this should serve to enhance the understanding of the Block’s contents and its role in the process and model.

• Unlike an Application or folder that can’t be referenced, you should not start your Block name with a number, because Pigment considers it as if it’s a number, not a Block name, which also breaks the referencing. This limitation can be overcome by using single quotes (‘ ‘) before typing any number.

How to name Boards

Board naming is all about clarity and prioritization within the View. Your end-users are likely to be navigating across Boards, so names should indicate what the Board contains. Board order should make sense for the business process. This means using two-digit numbers to order your Boards, and choosing full labels over acronyms or abbreviations.

Here is an example of best practice in Board naming:

How to name Views

When naming Views of Blocks, numbering is less important than clear labelling. Include the target user and the purpose of the View. “KPI”, “Graph” or “Chart” prefixes help make navigation easier when configuring Block Views in a Board. Sometimes it can be helpful to specify the role or persona that will be using the View for this Block as a prefix (e.g. “Department Head_Requests to validate”).