---
title: "Substitute a List with another List"
slug: "substitute-list"
description: "Learn how to effectively use Move and Substitute for Dimension Lists in Distributed Planning architecture to enhance governance and simplify management."
updated: 2026-04-28T08:22:39Z
published: 2026-04-28T08:22:39Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.pigment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Substitute a List with another List

When working with Distributed Planning (multiple linked Applications), you may need to reorganize your Dimension Lists for better control or simplicity. This article explains the two main options available in Pigment: Move and Substitute.

This feature applies only to Dimension Lists and does not support Transaction Lists.

## Move or Substitute a Dimension List

### Move

Use [Move](/v1/docs/move-list-to-another-application#why-would-you-move-a-list) to relocate an existing Dimension to another Application. When you move a Dimension, all existing data, formulas, and Views are updated to reference the new location. Data is not lost in the original Application. The List instead becomes shared from its new location. This action moves a List from one Application to another to support centralized governance and control.

**Example**

You build your Financial Planning & Analysis (FP&A) Application and later create a centralized data hub. To better manage shared Lists and access rights, you may want to centralize them in a single Application.

In this case, you move the Dimension to the centralized hub. Your data remains intact in the FP&A application because the List is now shared from the hub.

### Substitute

Use Substitute to modify your model by replacing one Dimension with another within an Application. This change is applied across all references. The substituted List replaces the original List in Metric structures, Property data types, Metric data types, Views, and formulas. When you substitute a Dimension, any data stored on the original Dimension is lost, but all references are automatically updated.

**Example** You have two Applications: FP&A and Hub. Both Applications include the same Dimension, `Country`. You may not want to move the Dimension from one Application to the other, as parts of each model already rely on it. Moving it would require manually updating the affected Blocks (Views and formulas).

Substitution, on the other hand, allows you to replace all references to one `Country` Dimension with the other. This action is performed at the Application level, meaning it impacts the entire Application, and the List must already exist within that Application.

## Substitute a List with another List

Substitute replaces all references of a Dimension List with another. Partial Substitute is not possible. That means that Metric Structure, Metric Type, Property Type, Views, and Formulas are impacted.

![Substituting Dimensions in an Application with options for month, quarter, and year.](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/KB - Substitute Dimensions in bulk (1).jpg)

> [!CAUTION]
> **🛡️****Warning**
> 
> You will lose any data inputs in Metrics where the original list is used as a Dimension. Data loss also occurs when the data type is set to the original List. This includes being used as a List Property. There may also be formula errors in specific cases. You can update these errors manually from the **Errors** page.

To substitute a List with another List:

1. Go to **Settings**in your Application.
2. Go to **General**, then select **Substitute Blocks.**
3. Select the Dimension to substitute, then choose the replacement Dimension from the drop-down menus and select **Substitute**.

> [!WARNING]
> ⚠️ **Important**
> 
> Dimension substitution may take several minutes, during which the Application structure is locked.
4. *(Optional)* Select **+ Add another**and repeat Step 3 to add another Dimension for substitution.
5. *(Optional)*Select **+ Add all in Folder** to add multiple Dimensions to substitute at once. Then, select **Autofill matching shared Dimensions by name**to match the selected Dimensions with Dimensions from the chosen Application that have similar names and automatically prefill them as replacement Dimensions.

> [!CAUTION]
> **🛡️****Warning**
> 
> This action can not be undone after initiating the substitute.

For more information on multi-Application architecture, see [Modeling Principles](/v1/docs/modeling-principles).