Versioning is fundamental in Pigment to structure your planning data across Actuals, Budgets, and Forecasts. Here are the essential concepts and steps to implement it effectively.
What is a version or a plan?
One of the most common use cases in Pigment is the creation of planning cycles (also known as version planning or scenario planning). This is where users build out a variety of plans based on their business data, with each plan leveraging different assumptions producing their own results. The final step is to compare these plans in variance reports, build waterfall charts to get actionable insights and save these plans for future reference.
Common types of plans
Budget: 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 shouldn’t be adjusted once finalised.
Reforecasts: Structured, periodic updates to the original forecast or budget (e.g. Q1, Q2, Q3 Reforecasts). These are used to reassess performance mid-year and adjust expectations based on new data.
Live Forecast / Rolling Forecast: 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.
ℹ️ Note
Budgets are static targets. Forecasts and Reforecasts are dynamic expectations that evolve with reality.
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 plan (as listed above) typically includes two types of data:
Actuals: Historical data from past months, imported directly from business systems (e.g. accounting data from NetSuite, sales data from Salesforce, employee data from HRIS).
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 Month logic, explained in Section 3.
Below are the key steps to building an efficient versioning system in Pigment, by leveraging a version Dimension, the switchover logic and the data type information—one that balances 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 will hold 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 will allow 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.
Why use a Version dimension instead of the Scenario feature?
Pigment’s Scenario feature is built for quick, ad-hoc comparisons—ideal for testing assumptions or simulating short-term impacts. It offers instant flexibility for exploring “what-if” cases without needing to modify your core model structure.
However, when it comes to structured, recurring planning cycles, the use of a Version Dimension is the more appropriate choice.
A Version Dimension is better suited for:
Long-term, structured planning processes like Budgets, Forecasts, and Reforecasts
Modeling at scale, since it behaves like any other Dimension and can be fully integrated into formulas, data blocks, and access controls
Initialising new planning cycles, leveraging features like “Clone Data”
Consistent reporting and variance analysis over time
Considerations regarding the Scenario feature for planning cycles:
Not treated as a classical Dimension, which limits its use in data blocks and formula logic
Less suitable for initialising new plans and managing user access
Not ideal for auditability or structured version tracking
ℹ️ Note
Use Scenarios for rapid “on-the-fly” simulations.
Use the Version Dimension when planning needs to be repeatable, auditable, and deeply integrated into your model
2. Populate the Dimension with Version Items
Add one Item per planning cycle in your Version Dimension to represent each version used (e.g. “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 the “Clone Data” feature, 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 will 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 will depend on your modeling and reporting needs.
Here are some considerations:
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 (e.g. 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 will be 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 (e.g. more granular calculations on 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:
Or like this (if you choose to include the optional Properties):
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 are illustrated with an example on Revenue Projections, but it 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 initialise new plans from existing ones