Has this ever happened to you?

You open the Playground to write a formula, but when you type in the name of the block you need, you see a dropdown list of multiple blocks, leaving you uncertain about which one to choose. 

For example, you need the Salary metric for existing employees, but you can’t tell from the list which “Salary” metric is for existing employees and which one 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

Naming conventions improve clarity and functionality at every level, helping everyone using your workspace. In this article, we’ll introduce the naming conventions we use in our templates and customer workspaces at the Application, Folder, Block, Board, and View level.

TLDR but still need the info? Skip to the bottom for the basic principles in handy bullet-point style.

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 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 will also explaining the purpose of the application, the roles involved and their actions, colour conventions, and any helpful definitions. 

How we Name Applications

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.”) will support having more than 9 applications and avoid this order: “1.” , “11.” , “12.” , “2”.

Below are the typical applications we create in Pigment and how we can name them:

• Hub: Contains shared dimensions, calendar, exchange rate, 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 following a numbering that reflect 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

For more insights on how to organise your workspace through multi application architecture you can read this article

How we Name Folders

Folder naming is similar to application naming, helping you order items within your workspace and making it easy to identify what will be inside without having to necessarily open it.

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:

00. Admin Folder: This folder, created in every application, contains the application-specific dimensions, variables metrics, and all admin blocks.   01. Library Folder: This folder contains “Pull” and “Shared” metrics connecting data between applications.   02./0X. Use Case-Specific Folders : These folders follow the business process covered and the calculation steps: import/input, assumptions, calculations, and outputs.

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.

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

How we Name Blocks

The naming of Blocks is by far the most import naming in Pigment as blocks names are referenced in formulas which will make formulas easy to write and to understand. So far, the naming conventions for different types of items have been very similar (and, spoiler alert, boards will be 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 will give 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.

Dimensions naming: need to be named simply and concisely, as they’re displayed as-is in the whole model, including in your boards. This means we’re 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 in a glimpse a Block role and usage in a model.

Format: 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 list of prefix A used 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 acronyme of the folder/sub-folder name. You can choose to use the folder/sub-folder numbers as prefix if you feel more comfortable doing so, just know that when referencing numbers you should open the quote mark in the formula bar or Pigment will consider that you’re typing numbers no names.

Here are some of the use case-specific prefixes we often use:

Of course, you should add your own prefixes to this list depending the specificities of your application. You can also combine multiple Prefix A to provide more detail on a Block 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 list of Prefix B is quite consistent across different models as block utilizations tend to remain similar or close to it.

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:

More advice on Block naming

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

• Using “(#) and “($)” or any other symbol or abbreviation can be helpful to provide more information about the metric use/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 assumption on Sales Quota

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

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

A quick note on referencing blocks:

• When referencing blocks in Pigment, typing an empty space indicates two separate objects. If you type the name without the space, the platform will surface metrics with a space as well. We don’t recommend using periods (.) or colons (:) in your block names because it will break 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, we do NOT recommend you start your block name with a number, because Pigment will consider it as if it’s a number, not a block name, which will end up in breaking the referencing too. This limitation can be overcome by using the single quote ‘ ‘ before starting to type any number.

How we Name Boards

Similarly to folders and applications, naming boards is all about clarity and prioritisation within the view. Your end users are likely to be navigating across boards, so it should be clear what will be found in the board, and they should be arranged in a way that makes 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 board naming: 

How we Name Views

When naming views of blocks, numbering is less important than clear labelling, including the target user and the purpose of the view. We will also use “KPI” or “Graph” or “Chart” prefixes to 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 (example: “Department Head_Requests to validate”).

Conclusion

Naming conventions are important for both navigability and accuracy in Pigment. By choosing a naming convention that works for your team, you can create a consistent way to arrange and reference your key items (applications, folders, blocks, views). We’ve offered our best practices as a guide, but the best choice will always be what works best for your team.

Naming conventions in a nutshell:

• Create a naming convention that suits your needs based on or inspired by the one we present in this article. Make sure to write it down on a board in each application and keep it up to date.

• Applications: Prefix with a 2-digit number for easy ordering – e.g. 03 Workforce Planning. Put the Hub first (00. Hub) and the rest in any logical order that makes sense for the use-cases applications.

• Folders: Use 2-digit numbers.

• Blocks:

  • For dimensions, keep the names concise yet descriptive, as these appear as-is throughout the application

  • For other block types, use a combination of prefix A (role & position) and B (utilisation) to name them, in order to enhances the understanding of their purpose

  • Don’t use colons or periods in your block names to not break the referencing

  • When referencing a block with a space in the name, type it without the space or Pigment will think you’re referencing 2 separate objects

• Boards: same as folders, with a focus on clarity of what’s inside and ordering based on process for the benefit of end users

• Views: numbering is less important than clarity of labelling based on the target user and the purpose of the view

• Ultimately, use whatever works best for your team and what will be used CONSISTENTLY!