Versioning is fundamental in Pigment as set out in Understand Versions in Pigment. This article provides the steps to implement versioning effectively.
Follow the steps below to build an efficient versioning system in Pigment, by leveraging:
a version Dimension
switchover logic
data types
Versioning systems configured this way balance flexibility for business needs with a clear and easy-to-maintain model architecture.
1. Create a Version Dimension
Start by creating a unique Version Dimension using a standard Dimension List. This holds all your Versions, for example:
Budget FY26
Forecast 3+9 FY26
Reforecast Q2 FY25 Pessimistic
Leveraging a Dimension List that can be referenced in formulas and used in the Metric structure to layer your data allows you to maintain the flexibility needed to address a wide range of planning processes and make sure you can meet all sorts of planning requirements.
2. Populate the Dimension with Version Items
Add one Item per planning cycle in your Version Dimension to represent each version used (such as “Budget 2024”, “Reforecast Q1 2025”). We recommend including either the creation year or the version window span in the name. Both naming approaches are valid and can be automated with formulas in your Version Dimension properties—the most important thing is to remain consistent and user-friendly.
ℹ️ Note
The year in the version name can refer to either the creation date or the period the plan covers—especially helpful when versions span multiple years.
Why Include the Creation Year/Window Span in the Version Name?
Using this structure improves clarity, helps maintain a clear, chronological record of your planning cycles, and simplifies version initialisation. Since each version acts as a data layer, you can quickly create new ones by copying assumptions from previous cycles using Clone data, saving time and ensuring consistency across planning iterations. By structuring versions by creation year or window span, you create a repeatable and scalable framework for planning across time.
3. Add Switchover Logic
Include a Switchover Month Property in your Version Dimension to define the last month of actual data that is to apply to each Version separately. This switchover logic ensures your forecast picks up where your actuals end, maintaining continuity for rolling forecasts.
Examples:
Budget FY26: contains actuals up to December 2025, pulled from source systems. The remaining months (January–December 2026) are projected using planning logic and assumptions.
Reforecast Q1 FY26: similar to Budget FY26, but includes actuals for the first three months of FY26 (e.g. Jan–Mar 2026). The remaining months (April–December 2026) are recalculated based on updated insights, making the forecast more accurate than Budget FY26.
ℹ️ Note
If your planning cycle is structured at the Year granularity instead of the Month, you can replace the Switchover Month property with a Switchover Year property instead. The approach remains the same: you still create one Version Item per planning cycle (based on creation year or version window span), and the switchover logic applies at the Year level when crossed with your Year Dimension.
Do You Need an “Actual” Version in Your Version Dimension?
Including an “Actual” version in your Version Dimension is optional: it depends on your modeling and reporting needs.
Benefits of having an “Actual” version
Simplified references in formulas: having a dedicated “Actual” version makes it easier to reference actuals explicitly in calculations, especially when comparing against other plans.
Improves reporting flexibility: useful for reporting gaps between Reforecast cycles. For example, if you’re using Q1, Q2, Q3 Reforecasts, an “Actual” version can display data for months that fall outside those planning versions—such as April and May before Q2 Reforecast begins.
Potential drawbacks
Redundant calculations: actuals are often already included in each plan version (via switchover logic), so the “Actual” version can introduce redundancy and additional recalculation of the same data.
Model Complexity: adding an “Actual” version introduces another layer to manage and maintain, which may not be necessary if your planning versions already include actual data where appropriate.
Recommendation: Use an “Actual” version only if:
You need to explicitly isolate actuals in formulas or reports
Your Reforecast cycle leaves gaps in actual coverage (for example, you need to pull your May actuals before the Q2 Reforecast starts)
Otherwise, you may choose to omit it and rely on switchover logic within each version to handle actual months—keeping your model simpler and leaner.
⚠️ Important
If you choose to include an “Actual” version in your Version Dimension, there’s no need to create multiple versions by year or time span (e.g. “Actuals 2023”, “Actuals 2024”). Instead, simply update the Switchover Month each new Month to bring in the latest actuals. This keeps your Version Dimension lean and avoids unnecessary duplication.
4. Add standard Properties for version management
Mandatory Properties in your Version Dimension
Include the following Properties in your Version Dimension to manage it effectively:
Start Month: The starting month of the version.
End Month: The ending month of the version.
These Properties are useful for defining the planning windows for each version: which months are to be populated with actual data, which month is to be populated with projections results.
Active Version: Boolean Property to identify the currently active versions that are displayed for either input or reporting.
Lock Version: Boolean Property to lock versions from edits once approved.
These Properties are used to calculate the Access Rights Metric applied in rules to define if a version is open for edit or locked. The “Actual” version is always locked for edit while the other versions are open for edit during the planning cycle, then locked once approved.
Optional Properties in your Version Dimension
You can decide to add more Properties if they suit your planning cycle process, but as opposed to the ones above, these are optional:
Version Type: Dimension type Property used to categorise the different types of versions you need to create (e.g. “Budget”, “Reforecast”, “Rolling Forecast”, “Long Range Planning”)
This Property is useful to:
Reference your “Actual” version if you use one, to avoid directly referencing the Version Item, reference the Version type instead and ensure full compatibility with the Test & Deploy requirements (read Manage Data Changes in Dimension Lists for more information).
Use different calculations rules based on the Version Type (for example, more granular calculations in Budget and Reforecast than in long-range planning).
Scenario: Dimension type Property used to categorise the different Scenario of a particular version you need to create (e.g. “Expected”, “Optimistic”, “Pessimistic”)
Version #: Incremental number of your version used to create different occurrences of a single version for comparison purposes. Ultimately these different occurrences should be deleted to keep a single validated version that is used later for reference.
Once set up, your Version Dimension should look like this:
The final name of your Versions can be automated through formulas based on the “Version Type”, “Planning Years” (using the Switchover Month+1) or “Creation Year”, and “Scenario” and “Version number” if you decide to use them.
⚠️ Important
Only keep active Versions currently used for planning or locked Versions needed for reference in this Dimension. Regularly review and clean up the Version list to avoid keeping unnecessary or outdated Items.
5. Create Key Version Metrics to layer the data by Versions
Create three Boolean Metrics to define the Month range for each version:
Is Version: TRUE for months between the starting month and ending month. Define the version window.
Is Actual: TRUE for months inside the version window until the Switchover Month (inclusive).
Is Plan: TRUE for months inside the Version window but after the Switchover Month.
When used in formulas, these Metrics allow you to:
Layer data correctly by version to bring actuals in each version depending on the Switchover Month
Apply different assumptions per version in your calculations and reports
6. Layer your Actual data and run your projection
The final step is to use your Key Version Metrics in formulas combined with Actual data and assumptions to calculate your version outputs. The following steps use a revenue projections example, but this step can be applied to any type of use case.
Create a “Revenue Actual” Metric by version
Create a “Forecast” Metric by version (including “Actuals” data in blue cells)
We now have a final Metric containing both our Actual data and Plan data depending on the Version’s Switchover Month, ready to be used in reporting and analysis.
Here is a simplified end-to-end illustration of all the different steps we followed so far:
7. (Optional) Display the Data Type for each version and month using the Mapped Dimension feature
Create a “Data Type” Metric by Version
Use this Metric to display the Data Type Dimension in the View using Mapped Dimensions
Once your “Data Type” Dimension has been mapped in the final Metric View, you can quickly identify Actual data and Plan data.
Final tips
Use a Version Dimension, where each Item is a plan per creation year or window span (except for the Actual version, if you need one)
Only apply the Version Dimension to the relevant data blocks to keep your model lean and efficient
Create new plans easily by adding Items to the Version Dimension
Use Clone Data to initialize new plans from existing ones