Territory Data Alignment

Territory Data Alignment

This skill activates when a practitioner needs to query, load, audit, or migrate account-to-territory and user-to-territory association data in an org using Enterprise Territory Management (ETM / Territory Management 2.0). It covers the data model objects, bulk DML patterns, coverage analysis SOQL, and the Track Territory Assignment History feature released as GA in Spring '25.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the org uses Territory Management 2.0 (ETM), not Legacy Territory Management. The objects are entirely different. ETM uses Territory2, ObjectTerritory2Association, and UserTerritory2Association. Legacy TM uses Territory, AccountTerritoryAssignment, and UserTerritory. Mixing them in queries is a common source of confusion.
• Know the target Territory2Model ID and its state. Associations can only be inserted against an Active territory model. Attempting to write associations against a Planning or Archived model returns an error. Query Territory2Model to confirm State = 'Active' before any DML.
• AssociationCause is set at insert time and cannot be updated. An ObjectTerritory2Association row has AssociationCause of either Territory (rule-driven) or Manual. Manual associations are created via API; rule-driven associations are created by assignment rule runs. You cannot change a row's AssociationCause after creation — to switch from manual to rule-driven you must delete and let the rule engine re-create.
• Track Territory Assignment History must be explicitly enabled in the org before history records are written. If it is not enabled, Territory2ModelHistory will exist as an object but will have no rows for assignment changes. Confirm feature status before relying on audit queries.

Core Concepts

ObjectTerritory2Association — Account-to-Territory Data Model

ObjectTerritory2Association is the junction object that links a Salesforce record (typically an Account) to a Territory2 node. Key properties:

• Fields: ObjectId (the Account ID or other supported object ID), Territory2Id, AssociationCause (Territory or Manual), IsDeleted, SystemModstamp.
• Queryable and insertable via API. You can SOQL query it directly and insert/delete rows using Bulk API 2.0, REST API, or Data Loader.
• One account can appear in multiple rows — once per territory it belongs to. Bulk deduplication checks are the caller's responsibility; the API does not prevent duplicate inserts.
• Deleting a manual association via API immediately removes territory access for that account. Rule-driven associations (AssociationCause = 'Territory') should be removed by changing the rule or running a rule that excludes the account, not by direct delete, as the rule engine may re-create them on the next run.
• Not all standard objects are supported — ObjectTerritory2Association is used for Accounts by default. Opportunity-to-territory linkage is handled separately via Opportunity Territory Assignment (not through this object).

UserTerritory2Association — User-to-Territory Data Model

UserTerritory2Association links a user to a Territory2 node, granting them membership in that territory. Key properties:

• Fields: UserId, Territory2Id, RoleInTerritory2 (Salesperson or Manager), IsActive.
• Queryable and insertable via API. Bulk loads of user-territory assignments are done via UserTerritory2Association inserts.
• RoleInTerritory2 affects forecast visibility, not record access. Both Salesperson and Manager members gain the same account record access within the territory; the role distinction only affects whether the user appears as a forecast manager in the territory forecast.
• Deactivating a user does not automatically remove their UserTerritory2Association rows. Stale rows for inactive users can inflate territory membership counts and affect forecast calculations. Coverage analysis should filter on User.IsActive = true.

Territory2ModelHistory and Track Territory Assignment History (Spring '25 GA)

Territory2ModelHistory captures field-level changes to Territory2Model records (model state transitions: Planning → Active → Archived). It does not, by default, capture individual account assignment events.

The Track Territory Assignment History feature, released as GA in Spring '25, extends ETM audit to record who assigned or removed an account from a territory and when. When enabled:

• A separate history tracking mechanism records ObjectTerritory2Association create and delete events, including the CreatedById and timestamp.
• UserTerritory2AssignmentHistory (available when feature is on) similarly captures user assignment and removal events.
• The feature must be enabled in Setup under Territory Settings. It is not on by default. History records begin accumulating from the moment the feature is enabled — there is no backfill of prior assignments.

Coverage Analysis with AssociationCause Filter

Coverage analysis means determining which accounts have territory coverage (at least one ObjectTerritory2Association row in an active model) and which do not. The AssociationCause filter is the key tool for distinguishing rule-driven from manual coverage:

• AssociationCause = 'Territory': assigned by an ETM assignment rule run. Stable and repeatable.
• AssociationCause = 'Manual': assigned directly via API or UI. May diverge from rule logic after a rule run if the manual association is not cleaned up.

Coverage gap detection requires a LEFT OUTER JOIN pattern: find Accounts where no ObjectTerritory2Association exists for the target territory model. In SOQL, this is achieved with a semi-join using NOT IN against the ObjectId set from ObjectTerritory2Association filtered by Territory2.Territory2Model.State = 'Active'.

Common Patterns

Bulk Insert of Manual Account-to-Territory Associations via Data Loader

When to use: You have a list of account-territory pairs (from a territory realignment exercise, a data migration, or a named account list) that need to be loaded into an Active ETM model without waiting for a rule run.

How it works:

1. Export current Territory2 records with their IDs: SELECT Id, Name, DeveloperName FROM Territory2 WHERE Territory2Model.State = 'Active'.
2. Prepare a CSV with columns: ObjectId (Account ID), Territory2Id, AssociationCause (set to Manual).
3. Validate for duplicates against existing associations: SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.State = 'Active' AND AssociationCause = 'Manual'.
4. Remove any rows from the CSV where the (ObjectId, Territory2Id) pair already exists.
5. Use Data Loader or Bulk API 2.0 to insert into ObjectTerritory2Association.
6. Verify: recount ObjectTerritory2Association rows per territory and spot-check five account-territory pairs in the UI.

Why not use the UI for bulk loads: The Territory Management UI supports individual account assignments but has no bulk import. API is the only path for loads above a few dozen records.

Coverage Gap Analysis SOQL

When to use: Determining which accounts have no active territory assignment — either as a pre-migration audit or a recurring operational health check.

How it works:

-- Step 1: Get all Account IDs that have at least one active territory association
SELECT ObjectId
FROM ObjectTerritory2Association
WHERE Territory2.Territory2Model.State = 'Active'

-- Step 2: Find Accounts NOT in that set
SELECT Id, Name, BillingState, AnnualRevenue
FROM Account
WHERE IsDeleted = false
  AND Id NOT IN (
    SELECT ObjectId
    FROM ObjectTerritory2Association
    WHERE Territory2.Territory2Model.State = 'Active'
  )
ORDER BY AnnualRevenue DESC NULLS LAST

For large orgs, run this with the Bulk API 2.0 query mode or Data Loader to avoid governor limit timeouts. The result set is the coverage gap list — accounts requiring either manual association or assignment rule adjustment.

AssociationCause breakdown query:

SELECT Territory2Id, Territory2.Name, AssociationCause, COUNT(Id) total
FROM ObjectTerritory2Association
WHERE Territory2.Territory2Model.State = 'Active'
GROUP BY Territory2Id, Territory2.Name, AssociationCause
ORDER BY Territory2.Name ASC

This shows how many accounts per territory are rule-driven vs. manually assigned — useful for auditing territory health before a rule rerun (which will re-evaluate rule-driven rows but leave manual rows in place).

Territory Model Migration — Copying Associations

When to use: Moving from one territory model to another (e.g., annual realignment, ETM model version bump). You need to carry manual associations from the old model to the new one; rule-driven associations will be re-created by the rule engine on the new model.

How it works:

1. Query manual associations from the old model: SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.DeveloperName = 'OldModel' AND AssociationCause = 'Manual'.
2. Map old Territory2Id values to new Territory2Id values using the territory DeveloperName as the stable key (IDs differ between models).
3. Build the new CSV using new Territory2Ids and AssociationCause = 'Manual'.
4. Activate the new model (only one model can be Active at a time).
5. Bulk insert into ObjectTerritory2Association against the now-Active new model.
6. Run assignment rules on the new model to populate rule-driven associations.
7. Verify gap analysis: compare account count in new model vs. old model.

Decision Guidance

Recommended Workflow

Step-by-step instructions for territory data alignment work:

1. Confirm the active territory model and feature state — Query Territory2Model to identify the Active model ID. Confirm whether Track Territory Assignment History is enabled in Setup. Confirm the target object type (Account is standard; other objects require custom ETM configuration).
2. Run a coverage baseline query — Use the coverage gap analysis SOQL pattern to determine how many accounts have no active territory association. Also run the AssociationCause breakdown query to see the ratio of rule-driven to manual assignments per territory. Document these numbers as the before-state.
3. Identify the data operation needed — Determine whether the goal is: (a) bulk insert of new manual associations, (b) cleanup of stale manual associations, (c) migration of associations to a new model, or (d) audit/reporting only. Select the appropriate pattern from Common Patterns.
4. Prepare and validate the data payload — For inserts: build the CSV with ObjectId, Territory2Id, AssociationCause. Deduplicate against existing rows. For deletes: query existing rows to get Id values — you delete by ObjectTerritory2Association.Id. For migrations: resolve Territory2Id mappings using DeveloperName as the stable key.
5. Execute the data operation via Bulk API 2.0 or Data Loader — For inserts/deletes exceeding a few hundred rows, use Bulk API 2.0 in parallel mode for throughput. Monitor job status via SELECT Id, State, NumberRecordsProcessed, NumberRecordsFailed FROM AsyncApexJob or the Bulk API job status endpoint.
6. Run post-operation verification — Re-run the coverage baseline queries and compare account counts per territory before and after. Spot-check five or more specific accounts in the Territory Management UI. If Track Territory Assignment History is enabled, verify that history records were written for the operation.
7. Document deviations and manual association rationale — Record why any accounts were manually assigned rather than rule-driven. Manual associations that survive a rule rerun are invisible to the rule logic — they can create silent coverage drift over time. Document the intent so future rule runs or realignments can account for them.

Review Checklist

Run through these before marking territory data alignment work complete:

• Active territory model confirmed; no attempt made to write to Planning or Archived models
• AssociationCause is correctly set for all inserted rows (Manual for API-driven inserts)
• Duplicate check completed before bulk insert (no duplicate ObjectId + Territory2Id pairs)
• Coverage gap analysis run before and after the operation; gap count reduced as expected
• AssociationCause breakdown query shows expected ratio of rule vs. manual assignments
• For model migrations: Territory2Id mapping validated using DeveloperName (not ID) as the stable key
• Stale UserTerritory2Association rows for inactive users identified and addressed
• If Track Territory Assignment History is enabled, audit records verified for key association events
• Bulk API 2.0 job completed with zero or acceptable failed records; failed record log reviewed
• Manual association rationale documented for any account forced outside rule-driven logic

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. AssociationCause is immutable — rule reruns do not remove manual associations — When you run or rerun ETM assignment rules, the rule engine creates and deletes rows with AssociationCause = 'Territory'. Rows with AssociationCause = 'Manual' are never touched by rule runs. This means a manually assigned account will remain in a territory even if its account fields no longer match the rule criteria. Over time, manual associations silently diverge from rule logic. Audit manual associations regularly and document the rationale for each.

2. Direct delete of rule-driven rows is temporary — If you delete an ObjectTerritory2Association row where AssociationCause = 'Territory', the next assignment rule run will re-create it if the account still matches the territory's criteria. You must modify the rule or exclude the account from rule criteria to permanently remove a rule-driven association.

3. Only one Active territory model at a time — transition is not instantaneous — Activating a new territory model and archiving the old one is a sequential process. During the transition window, account record access through territories may be temporarily inconsistent. Plan model migrations during low-traffic windows, and validate that the new model is fully activated and rules have run before communicating go-live to users.

4. Track Territory Assignment History does not backfill — Enabling the feature after the fact gives you a clean history log starting from the enablement date. All prior territory assignment events (including the initial bulk load) are not captured. If you need a historical snapshot, export ObjectTerritory2Association before enabling and store it externally.

5. SOQL governor limits apply to coverage gap NOT IN subqueries — A query like SELECT Id FROM Account WHERE Id NOT IN (SELECT ObjectId FROM ObjectTerritory2Association ...) is subject to the 50,000-row subquery row limit in synchronous SOQL. For orgs with more than 50K account-territory associations, this query will fail or return incomplete results in a synchronous context. Use Bulk API 2.0 query or split the analysis into batches.

Output Artifacts

Related Skills

• admin/territory-design-requirements — use before data alignment work to ensure the territory hierarchy and assignment rule criteria are correct; data alignment should follow design, not precede it
• apex/territory-api-and-assignment — use for Apex-driven territory assignment logic, trigger-based association management, and programmatic rule invocation
• data/opportunity-pipeline-migration — use when territory alignment changes co-occur with opportunity data migration (territory changes affect opportunity territory assignment)