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:
- Export current
Territory2 records with their IDs: SELECT Id, Name, DeveloperName FROM Territory2 WHERE Territory2Model.State = 'Active'.
- Prepare a CSV with columns:
ObjectId (Account ID), Territory2Id, AssociationCause (set to Manual).
- Validate for duplicates against existing associations:
SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.State = 'Active' AND AssociationCause = 'Manual'.
- Remove any rows from the CSV where the (ObjectId, Territory2Id) pair already exists.
- Use Data Loader or Bulk API 2.0 to insert into
ObjectTerritory2Association.
- 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:
- Query manual associations from the old model:
SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.DeveloperName = 'OldModel' AND AssociationCause = 'Manual'.
- Map old
Territory2Id values to new Territory2Id values using the territory DeveloperName as the stable key (IDs differ between models).
- Build the new CSV using new Territory2Ids and
AssociationCause = 'Manual'.
- Activate the new model (only one model can be Active at a time).
- Bulk insert into
ObjectTerritory2Association against the now-Active new model.
- Run assignment rules on the new model to populate rule-driven associations.
- Verify gap analysis: compare account count in new model vs. old model.
Decision Guidance
| Situation |
Recommended Approach |
Reason |
| Need to assign specific accounts to territories outside rule logic |
Insert ObjectTerritory2Association rows with AssociationCause = 'Manual' via Bulk API 2.0 |
Rule engine will not overwrite manual rows; manual inserts are immediately effective |
| Need to remove a rule-driven association |
Modify or deactivate the assignment rule, then rerun rules |
Direct delete of rule-driven rows will be re-created by the next rule run |
| Coverage gap analysis for large orgs (>100K accounts) |
Use Bulk API 2.0 query for the NOT IN subquery — standard SOQL will hit governor limits |
Large subqueries in standard SOQL context hit 50K row limits; Bulk API avoids this |
| Audit who assigned an account to a territory |
Enable Track Territory Assignment History in Setup; query history records |
Feature must be on before events are recorded — no retroactive data |
| Migrating territory associations to a new model |
Map via Territory2.DeveloperName, export manual rows only, bulk insert into new model |
Rule-driven rows should be re-created by running rules on the new model; only manual rows require migration |
| User-territory membership is stale after rep turnover |
Bulk delete UserTerritory2Association rows for inactive users; bulk insert for new reps |
Deactivating a user in Salesforce does not remove their territory memberships |
| Determining if an account's territory is rule-assigned or manually assigned |
Filter ObjectTerritory2Association on AssociationCause |
The field is immutable after insert — it accurately reflects the assignment origin |
Recommended Workflow
Step-by-step instructions for territory data alignment work:
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
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.
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.
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.
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.
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
| Artifact |
Description |
| Coverage gap report |
List of Account IDs and basic fields with no active ObjectTerritory2Association row in the active model |
| AssociationCause breakdown table |
Per-territory count of rule-driven vs. manual associations, used to assess territory health |
| Bulk insert CSV |
ObjectId, Territory2Id, AssociationCause CSV ready for Data Loader or Bulk API 2.0 insert into ObjectTerritory2Association |
| Territory model migration mapping |
Old Territory2Id to new Territory2Id mapping table keyed on DeveloperName |
| UserTerritory2Association audit |
List of UserTerritory2Association rows for inactive users requiring cleanup |
| Audit query set |
SOQL queries leveraging Territory2ModelHistory and Track Territory Assignment History records |
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)
1---2name: territory-data-alignment3description: "Use this skill when querying, migrating, auditing, or maintaining account-to-territory and user-to-territory data in a Salesforce Enterprise Territory Management (ETM) org. Covers ObjectTerritory2Association DML via API, UserTerritory2Association data, Territory2ModelHistory audit queries, the Track Territory Assignment History feature (GA Spring '25), coverage analysis SOQL with AssociationCause filter, and data migration of territory associations between models. Trigger keywords: ObjectTerritory2Association, UserTerritory2Association, territory assignment data, territory coverage analysis, territory association bulk load, ETM data migration, track territory assignment history. NOT for ETM configuration or territory model setup — use territory-design-requirements for that. NOT for territory rule creation or activation — those are admin concerns."4category: data5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Reliability9 - Security10triggers:11 - "how do I query which accounts are assigned to which territories in ETM"12 - "I need to bulk load account-to-territory associations using the API or Data Loader"13 - "how do I audit territory assignment changes and who manually assigned an account to a territory"14 - "we are migrating to a new territory model and need to copy account assignments across"15 - "how do I find gaps in territory coverage — accounts that are not assigned to any territory"16 - "what is the difference between rule-driven and manual territory assignments in the data model"17 - "how do I use the Track Territory Assignment History feature released in Spring 25"18tags:19 - etm20 - territory-management-221 - ObjectTerritory2Association22 - UserTerritory2Association23 - Territory2ModelHistory24 - territory-assignment25 - coverage-analysis26 - data-migration27 - audit28inputs:29 - target territory model ID or developer name30 - list of account IDs or a SOQL filter defining the account population to assess31 - whether the goal is read/audit, bulk insert, or migration between models32 - ETM feature flags enabled in the org (Track Territory Assignment History, Territory2Model state)33 - intended AssociationCause for new associations (Territory or Manual)34outputs:35 - SOQL queries for coverage analysis, gap detection, and AssociationCause audit36 - Data Loader or Bulk API 2.0 CSV structure for ObjectTerritory2Association inserts37 - step-by-step migration procedure for moving associations between territory models38 - audit query set using Territory2ModelHistory and UserTerritory2AssignmentHistory39 - coverage gap report template (accounts with no active territory association)40dependencies: []41version: 1.0.042author: Pranav Nagrecha43updated: 2026-04-0644metadata:45 source: https://skillmd.com/skills/banibratachatterjee/territory-data-alignment46---4748# Territory Data Alignment4950This 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.5152---5354## Before Starting5556Gather this context before working on anything in this domain:5758- **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.59- **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.60- **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.61- **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.6263---6465## Core Concepts6667### ObjectTerritory2Association — Account-to-Territory Data Model6869`ObjectTerritory2Association` is the junction object that links a Salesforce record (typically an Account) to a `Territory2` node. Key properties:7071- **Fields:** `ObjectId` (the Account ID or other supported object ID), `Territory2Id`, `AssociationCause` (`Territory` or `Manual`), `IsDeleted`, `SystemModstamp`.72- **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.73- **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.74- **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.75- **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).7677### UserTerritory2Association — User-to-Territory Data Model7879`UserTerritory2Association` links a user to a `Territory2` node, granting them membership in that territory. Key properties:8081- **Fields:** `UserId`, `Territory2Id`, `RoleInTerritory2` (`Salesperson` or `Manager`), `IsActive`.82- **Queryable and insertable via API.** Bulk loads of user-territory assignments are done via `UserTerritory2Association` inserts.83- **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.84- **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`.8586### Territory2ModelHistory and Track Territory Assignment History (Spring '25 GA)8788`Territory2ModelHistory` captures field-level changes to `Territory2Model` records (model state transitions: Planning → Active → Archived). It does not, by default, capture individual account assignment events.8990The **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:9192- A separate history tracking mechanism records `ObjectTerritory2Association` create and delete events, including the `CreatedById` and timestamp.93- `UserTerritory2AssignmentHistory` (available when feature is on) similarly captures user assignment and removal events.94- **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.9596### Coverage Analysis with AssociationCause Filter9798Coverage 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:99100- `AssociationCause = 'Territory'`: assigned by an ETM assignment rule run. Stable and repeatable.101- `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.102103Coverage 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'`.104105---106107## Common Patterns108109### Bulk Insert of Manual Account-to-Territory Associations via Data Loader110111**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.112113**How it works:**1141151. Export current `Territory2` records with their IDs: `SELECT Id, Name, DeveloperName FROM Territory2 WHERE Territory2Model.State = 'Active'`.1162. Prepare a CSV with columns: `ObjectId` (Account ID), `Territory2Id`, `AssociationCause` (set to `Manual`).1173. Validate for duplicates against existing associations: `SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.State = 'Active' AND AssociationCause = 'Manual'`.1184. Remove any rows from the CSV where the (ObjectId, Territory2Id) pair already exists.1195. Use Data Loader or Bulk API 2.0 to insert into `ObjectTerritory2Association`.1206. Verify: recount `ObjectTerritory2Association` rows per territory and spot-check five account-territory pairs in the UI.121122**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.123124### Coverage Gap Analysis SOQL125126**When to use:** Determining which accounts have no active territory assignment — either as a pre-migration audit or a recurring operational health check.127128**How it works:**129130```soql131-- Step 1: Get all Account IDs that have at least one active territory association132SELECT ObjectId133FROM ObjectTerritory2Association134WHERE Territory2.Territory2Model.State = 'Active'135136-- Step 2: Find Accounts NOT in that set137SELECT Id, Name, BillingState, AnnualRevenue138FROM Account139WHERE IsDeleted = false140 AND Id NOT IN (141 SELECT ObjectId142 FROM ObjectTerritory2Association143 WHERE Territory2.Territory2Model.State = 'Active'144 )145ORDER BY AnnualRevenue DESC NULLS LAST146```147148For 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.149150**AssociationCause breakdown query:**151152```soql153SELECT Territory2Id, Territory2.Name, AssociationCause, COUNT(Id) total154FROM ObjectTerritory2Association155WHERE Territory2.Territory2Model.State = 'Active'156GROUP BY Territory2Id, Territory2.Name, AssociationCause157ORDER BY Territory2.Name ASC158```159160This 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).161162### Territory Model Migration — Copying Associations163164**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.165166**How it works:**1671681. Query manual associations from the old model: `SELECT ObjectId, Territory2Id FROM ObjectTerritory2Association WHERE Territory2.Territory2Model.DeveloperName = 'OldModel' AND AssociationCause = 'Manual'`.1692. Map old `Territory2Id` values to new `Territory2Id` values using the territory `DeveloperName` as the stable key (IDs differ between models).1703. Build the new CSV using new Territory2Ids and `AssociationCause = 'Manual'`.1714. Activate the new model (only one model can be Active at a time).1725. Bulk insert into `ObjectTerritory2Association` against the now-Active new model.1736. Run assignment rules on the new model to populate rule-driven associations.1747. Verify gap analysis: compare account count in new model vs. old model.175176---177178## Decision Guidance179180| Situation | Recommended Approach | Reason |181|---|---|---|182| Need to assign specific accounts to territories outside rule logic | Insert `ObjectTerritory2Association` rows with `AssociationCause = 'Manual'` via Bulk API 2.0 | Rule engine will not overwrite manual rows; manual inserts are immediately effective |183| Need to remove a rule-driven association | Modify or deactivate the assignment rule, then rerun rules | Direct delete of rule-driven rows will be re-created by the next rule run |184| Coverage gap analysis for large orgs (>100K accounts) | Use Bulk API 2.0 query for the NOT IN subquery — standard SOQL will hit governor limits | Large subqueries in standard SOQL context hit 50K row limits; Bulk API avoids this |185| Audit who assigned an account to a territory | Enable Track Territory Assignment History in Setup; query history records | Feature must be on before events are recorded — no retroactive data |186| Migrating territory associations to a new model | Map via `Territory2.DeveloperName`, export manual rows only, bulk insert into new model | Rule-driven rows should be re-created by running rules on the new model; only manual rows require migration |187| User-territory membership is stale after rep turnover | Bulk delete `UserTerritory2Association` rows for inactive users; bulk insert for new reps | Deactivating a user in Salesforce does not remove their territory memberships |188| Determining if an account's territory is rule-assigned or manually assigned | Filter `ObjectTerritory2Association` on `AssociationCause` | The field is immutable after insert — it accurately reflects the assignment origin |189190---191192## Recommended Workflow193194Step-by-step instructions for territory data alignment work:1951961. **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).1972. **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.1983. **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.1994. **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.2005. **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.2016. **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.2027. **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.203204---205206## Review Checklist207208Run through these before marking territory data alignment work complete:209210- [ ] Active territory model confirmed; no attempt made to write to Planning or Archived models211- [ ] `AssociationCause` is correctly set for all inserted rows (`Manual` for API-driven inserts)212- [ ] Duplicate check completed before bulk insert (no duplicate ObjectId + Territory2Id pairs)213- [ ] Coverage gap analysis run before and after the operation; gap count reduced as expected214- [ ] `AssociationCause` breakdown query shows expected ratio of rule vs. manual assignments215- [ ] For model migrations: `Territory2Id` mapping validated using `DeveloperName` (not ID) as the stable key216- [ ] Stale `UserTerritory2Association` rows for inactive users identified and addressed217- [ ] If Track Territory Assignment History is enabled, audit records verified for key association events218- [ ] Bulk API 2.0 job completed with zero or acceptable failed records; failed record log reviewed219- [ ] Manual association rationale documented for any account forced outside rule-driven logic220221---222223## Salesforce-Specific Gotchas224225Non-obvious platform behaviors that cause real production problems:2262271. **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.2282292. **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.2302313. **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.2322334. **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.2342355. **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.236237---238239## Output Artifacts240241| Artifact | Description |242|---|---|243| Coverage gap report | List of Account IDs and basic fields with no active `ObjectTerritory2Association` row in the active model |244| AssociationCause breakdown table | Per-territory count of rule-driven vs. manual associations, used to assess territory health |245| Bulk insert CSV | `ObjectId`, `Territory2Id`, `AssociationCause` CSV ready for Data Loader or Bulk API 2.0 insert into `ObjectTerritory2Association` |246| Territory model migration mapping | Old `Territory2Id` to new `Territory2Id` mapping table keyed on `DeveloperName` |247| UserTerritory2Association audit | List of `UserTerritory2Association` rows for inactive users requiring cleanup |248| Audit query set | SOQL queries leveraging `Territory2ModelHistory` and Track Territory Assignment History records |249250---251252## Related Skills253254- 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 it255- apex/territory-api-and-assignment — use for Apex-driven territory assignment logic, trigger-based association management, and programmatic rule invocation256- data/opportunity-pipeline-migration — use when territory alignment changes co-occur with opportunity data migration (territory changes affect opportunity territory assignment)