Territory2Model Metadata Type in SFDX

Architectural Overview#

The Territory2Model metadata type represents the root structural container and lifecycle controller for Enterprise Territory Management (ETM / Territory2) in Salesforce. Unlike legacy territory management, which supported only a single monolithic, continuously active hierarchy, Territory2 empowers sales operations and platform architects to build, simulate, and stage entire alternative sales organizational designs.

Architecturally, Territory2Model manages three discrete lifecycle states:

• Planning: The sandbox where sales architects construct new territory trees, create Territory2Rule criteria, and simulate account assignment metrics without disrupting active production account sharing.
• Active: The currently operational territory model driving runtime account sharing, opportunity visibility, and territory forecasting. Only one model can be active at any given moment.
• Archived: Historical models preserved for audit trails, reporting comparisons, and regulatory review.

Deploying Territory2Model metadata enables enterprise organizations to orchestrate annual territory realignments cleanly through automated CI/CD pipelines.

Directory and File Conventions#

In SFDX source projects, Territory2Model definitions reside at the root of their specific model folder inside territory2Models:

Key Metadata Fields#

The Territory2Model metadata schema governs lifecycle status and descriptions:

Declarative XML and Package Manifest Examples#

Below is a declarative Territory2Model definition configuring a Planning model for the upcoming fiscal year:

<?xml version="1.0" encoding="UTF-8"?>
<Territory2Model xmlns="http://soap.sforce.com/2006/04/metadata">
    <name>FY27 Global Sales Model</name>
    <description>Strategic realignment of enterprise and commercial sales territories for fiscal year 2027.</description>
    <state>Planning</state>
</Territory2Model>

Add the model to package.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>FY27_Global_Sales</members>
        <name>Territory2Model</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

Manage territory models via the Salesforce CLI:

# Retrieve the entire territory model including child territories and rules
sf project retrieve start --metadata "Territory2Model:FY27_Global_Sales"

# Deploy territory model in Planning state to production
sf project deploy start --metadata "Territory2Model:FY27_Global_Sales" --target-org prod

# Query model states using Tooling API
sf data query --query "SELECT Id, DeveloperName, State FROM Territory2Model" --use-tooling-api

Senior Architect Considerations#

1. Activation Strategy: Model activation triggers an org-wide asynchronous batch recalculation that updates millions of AccountShare records. Always execute activation via the UI or Tooling API during designated off-peak maintenance windows.
2. Model Archival: When promoting a new model to Active, the existing active model automatically transitions to Archived. Archived models cannot be re-activated directly; they must first be cloned back to Planning.
3. CI/CD Best Practice: Package all child Territory2 nodes and Territory2Rule components within the model directory to maintain atomic version control.

Frequently asked questions

What is the role of Territory2Model in Salesforce?

Territory2Model represents the complete sales territory hierarchy container, managing lifecycle states like Planning, Active, and Archived.

Which folder stores Territory2Model files in SFDX?

They are stored in force-app/main/default/territory2Models/ModelName with the ModelName.territory2Model-meta.xml file extension.

How many active Territory2Models can exist in an org simultaneously?

Only one Territory2Model can be in the Active state at any given time, though multiple models can exist in Planning or Archived states.

Can a Territory2Model be deployed directly in Active state?

It is best practice to deploy in Planning state, verify hierarchy and rule assignments, and then transition to Active via Setup or CLI.