Understand Versions in Pigment

Versioning is a key concept in Pigment and in planning generally. While it's been called many things throughout the history of Enterprise Performance Management (EPM)—like Scenario, Cycle, or Plan—at Pigment, it’s known as Version.

This article introduces the concept, outlines the key architectural choices it drives, shows how to combine it with features like Scenario and Snapshot, and explains how to keep your numbers consistent.

Before you begin

What is a Version or a plan?

One of Pigment’s most common use cases is the creation of planning cycles (also known as version planning or scenario planning). Modelers build out a variety of plans based on their business data, with each plan using different assumptions and producing their own results. These plans are used in variance reports to derive actionable insights.

Common types of plans

Plans are often one of the following:

Budgets: a fixed annual plan, usually built at the start of the fiscal year. It serves as a target for both internal and external stakeholders and acts as a baseline to measure performance. Budgets should not be adjusted once finalized.
Reforecasts: structured, periodic updates to the original forecast or budget (such as Q1, Q2, Q3 Reforecasts). These are used to reassess performance mid-year and adjust expectations based on new data.
Live forecasts / rolling forecasts: an evolving plan that reflects the most realistic expectation of business performance. It combines actuals to date with forecasted data for future months and is regularly updated to stay aligned with current trends.

Each of these plans can be broken down into several Versions, each containing different assumptions, such as:

Reforecast Q2 Optimistic
Reforecast Q2 Expected
Reforecast Q2 Pessimistic

Types of data in a plan

Each of the plan types above typically includes two types of data:

Actuals: historical data from past months, imported directly from business systems (including accounting data from NetSuite, sales data from Salesforce, employee data from HRIS for example).
Plan data: future-looking data generated through projections, assumptions, and calculations.

The way these two types of data are combined is specific to each Version created and is managed through a switchover logic. For more information and the key steps to building an efficient versioning system in Pigment, see Implement Versions and plans in Pigment.

ℹ️ Note
The guidance below mainly refers to the Finance use case, but these concepts apply equally to Supply Chain and Sales Planning.

The Version Dimension

Most of your Pigment Applications comprise Metrics, structured by Dimensions. To use Versions, the fundamental rule is that all Metrics must have a Version Dimension.

This allows you to have a different set of values depending on the specific Version, making your Pigment Application adaptable to all types of plans. This means you can use the same inputs, formulas, and ultimately the same Boards for all your different Versions.

There are a few exceptions where a Metric's value does not depend on Version, such as Metrics containing only Actuals data.

Multi-Application Strategy

Given Pigment's distributed planning approach, you may have several Applications. For more information, see Multi-Application Architecture: Why and How?.

Dos and don’ts

Aim to use the same Version Dimension in as many of your Applications as possible.
Keep the Version Dimension in your Hub application and share it with the remaining Applications (such as HR, Revenue, OPEX, Reporting). This ensures your values flow seamlessly and all your plans stay in sync.
If there is a specific business need for a different Version cadence, such as the sales team needing ten times as many versions as the rest of the company, create a separate Version Dimension for them.

Manage external data loads

Most of your external data is loaded into Transaction Lists, which do not have Versions. For this data, we apply a switchover logic:

Date every Version with a "last actual data" date.
Any data loaded after that date is not considered for Version.
- Example: if your Q1 forecast is dated April 1, any external data loaded after April 1 does not impact that forecast.
Use different switchover dates for your Versions—for example, one for accounting data and another for HR/employee roster data.

For more information on implementing switchover logic, see Implement Versions and plans in Pigment.

Versions in the Planning Process: Snapshots and Clones

When your planning cycle comes to an end, there are two key steps you'll need to take:

1. Close the last cycle: use Snapshots

Pigment is a live calculation engine. Everything you keep in an Application is recalculated if any inputs or formulas change. The exception to this is the Snapshot. Take a Snapshot of your Applications at the end of every planning cycle, or every month if you use Rolling Forecasting, to freeze them in time.

2. Initiate the next Version: clone your Data

Create new Versions by cloning data from your latest plan. For example, imagine you’ve just finished "Board Plan Y+1" and taken a Snapshot, and now you want to start "Forecast M+1":

Add a "Forecast M+1" Item in your Version Dimension.
Clone the data (for every Application using the Dimension) from “Board Plan Y+1” into “Forecast M+1”.
Change the switchover date for the new version.

“Forecast M+1” is now ready for your end-users. The original “Board Plan Y+1” remains as a live copy, allowing you to make future modifications, such as moving budget between departments or seeing the impact of a re-organization.

ℹ️ Note
Keeping many live versions can potentially slow down your Applications due to continuous recalculations. Try keeping a maximum of six live versions (for example: Current forecast, Last forecast, Board Plan, Board Plan v2, 3YP), and using Snapshots to store historical data.

Adapting calculations in live Versions

Since a cloned version is live, changing the formulas to reflect new business conditions impacts all Versions using that Metric. Manage this by tracking these changes:

Create a Boolean setting on your Version Dimension, called "Y+1 logic changes" for example.
Reference the setting in your formulas using an IF statement:
IF(Y+1 Logic Changes, New formula, Old formula)

This makes it explicit which logic you have changed and when.

Manage changes to past data

Certain changes to your Application structure or inputs can modify your past data. Below are some suggested techniques to manage past data changes:

Change type	Technique
Formula changes: If you change a formula, all live Versions that use it are recalculated.	Use explicit IF statements with a Boolean setting on your Version Dimension to manage which Versions use the old logic and which use the new.
Metric structure changes: Altering the Dimensions or structure of a Metric can break historical integrity.	Save the old data before you alter the structure: make a copy of the Metric, transfer data with BY, change the structure, and reenter the data using BY.
Changes to reporting Properties/parents: This fundamentally just moves numbers around—which might be exactly what you want if you're reflecting a re-org.	If you need to keep a record of the original historical groupings, create a "historical" Property in your Dimension to save those structures.
Reloads of historical data: If your saved Versions rely on Actuals for planning, reloading historical data impacts them.	To preserve the original values used, save prior Actuals values in a copy Metric at the source of your Transaction List for that specific Version.
Deletions of Dimension Items: This is not advised: deleting an Item is a structural change and can cause significant problems.	Avoid deleting Dimension Items in a production system. Only undertake this during a controlled annual administrative process.

How other Pigment tools work with Versions

Scenarios: use Scenarios to simulate things that are not in your current logic. Test logic and inputs in Scenarios first, validate the change, and then incorporate it into the main Version model as described above.
Data slices: create Metrics displaying data in Versions, Years and any other kind of Dimension simply, using Data slices.