Territory Management Using ATL

The Account Territory Loader (ATL) is used for Territory management. The New Account and New Record Type wizards create ATL objects when a user creates Accounts. The wizards also perform a Territory realignment for the current user.

Salesforce provides a few simple capabilities to explicitly add an Account to a Territory, yet data loading explicit Account-to-Territory bulk assignments can be challenging. Veeva CRM’s Account Territory Loader utility can be leveraged to better assist with adding one or many Territories to one or many Accounts. This utility provides the ability to list the Account and Territory names each Account should be assigned to without the complexities of the Territory, Group or ObjectTerritory2Association objects.

Because CRM has many other methods of assigning Accounts to Territories, an Account’s ATL record may not have the full list of Territories an Account is currently assigned to. Salesforce’s ObjectTerritory2Association table always contains the most accurate list of which Users and Territories have access to an Account.

Prerequisites

  • User has permission to create ATL objects and edit access to all fields on the ATL object
  • User does not have Edit permission to the Territory_vod field on the Account object
  • All Account and Territory records have been loaded into CRM

Fields

The Account_Territory_Loader_vod object has five important fields:

  • Account_vod [Lookup to Account] – Contains the Account SFDC 18-character ID for the account to be aligned
  • External_ID_vod [Text] – Must contains the Account SFDC 18-character ID for the account to be aligned
  • Territory_vod [Long Text Area 1500] – Contains a semicolon-delimited list of territories to assign to the account
  • Territory_to_Add_vod [Text 255] – Contains a semicolon delimited list of territory names. Used to assign one or more territories to the account for incremental alignments.
  • Territory_to_Drop_vod [Text 255] – Contains a semicolon delimited list of territory names. Used to remove one or more territories from the account for incremental alignments.

There should only be one record in the Account_Territory_Loader_vod for each account. After the initial load, you should be able to perform an upsert on this object based on the External_ID_vod field.

Two triggers exist when inserting and updating a record in Account_Territory_Loader_vod. The first trigger checks the value of the Territory_to_Add_vod and Territory_to_Drop_vod fields. If a value exists in the Territory_to_Drop_vod field, then the trigger will look for the referenced territory name(s) in the Territory_vod field and remove it. If there is a value in the Territory_to_Add_vod field, the trigger will add the territory name(s) to the Territory_vod field if it’s not already listed. Then the trigger clears these fields.

The second trigger performs the alignment logic. It first clears the ObjectTerritory2Association records that correspond to the current Territory Assignments. The trigger then parses the territory names in the Territory_vod field and loops through the territories to assign to the account.

This approach has performance advantages over using Zip to Terr and creating Assignment Rules on the SFDC Territory Hierarchy.

Data Loading Best Practice

The following are basic recommendations when loading ATL records via an external data loader or the SFDC API. It is assumed that all Territory and Account records exist in Veeva CRM prior to loading ATL records.

Inserting ATL Records

The initial ATL record creation should include the following fields:

  • Account_vod
  • External_Id_vod
  • Territory_To_Add_vod

Updating ATL Records

It is best practice to use the Territory_To_Add_vod and Territory_To_Drop_vod fields as often as possible when updating ATL records. Updating or Upserting ATL records should include the following fields:

  • Account_vod__c (Account.Id)
  • External_Id_vod__c (Account.Id) (match on)
  • Territory_To_Add_vod__c or Territory_To_Drop_vod__c (semicolon delimited list of each Territory.Name) (eg. 101;104;Chicago South 308)

Account Territory Loader Processing

The ATL object offers two methods of processing changes made to ATL records.

  • Classic ATL Approach: Each ATL insert and update masters the Account assignments by first clearing each Territory assigned to the Account and re-inserting only the Territories listed in the Territory_vod field. This approach is known as “wipe and replace”.
  • Incremental ATL Approach: Unlike the classic approach of wipe and replace, the incremental approach only processes changed values made to the Territory_vod field.

Veeva CRM orgs can be configured to use one of the approaches via the Territory_Settings_vod Custom Setting.

Classic ATL Processing Approach

The classic processing approach assumes the values listed in the Territory_vod field are the desired list of Territories, regardless of what is listed in the ObjectTerritory2Association table for an Account.

When the ATL_Mode_vod field on the Territory_Settings_vod object has a value of 0 or is blank, which is the default setting, the following happens on an account merge:

  • The ATL record for the winning account is preserved
  • Territory assignments included in the Territory_vod field on the ATL record of the losing account are appended to the Territory_vod field of the ATL record for the winning account and the assignments are preserved
  • Territory assignments manually created in Salesforce that did not exist on the ATL record of the losing account are removed
  • The ATL record for the losing account is deleted

Each ATL insert or update processes the following: 

  • A trigger takes the values found in Territory_To_Add_vod and/or Territory_To_Drop_vod fields and add or remove the respective Territory values in the Territory_vod field. The Territory_To_Add/Drop_vod fields are cleared
  • All ObjectTerritory2Association rows for the Account where ObjectTerritory2Association.AssociationCause=Territory2Manual are deleted
  • A trigger parses the Territory_vod field and inserts a new ObjectTerritory2Association row for each Territory listed in the Territory_vod field.

Incremental ATL Processing Approach

For some Veeva CRM environments, the classic approach adversely affects Account to Territory assignments from other alignment methods. The “wipe and replace” method may delete valid Territory assignments listed in the ObjectTerritory2Association table but not listed on the ATL record.

This is especially true for Account to Territory assignments that come from outside of Veeva CRM (such as Veeva Align). Some of these systems do not use ATL for Territory management. Instead, Account-to-Territory assignments are inserted directly into the CRM ObjectTerritory2Association object.

This is why the incremental processing approach is available. It allows a Veeva CRM Org to continue using the ATL utility in conjunction with outside Account to Territory assignment systems that do not use ATL.

When the ATL_Mode_vod field on the Territory_Settings_vod object has a value of 1, the following happens on an account merge:

  • The ATL record for the winning account is preserved
  • Territory assignments of the losing account are reparented to the winning account
  • If the assignment being reparented existed on the ATL record of the losing account, the Territory Name is appended to the Territory_vod field on the winning ATL record
  • If the assignment being reparented was manually created in Salesforce and did not exist on the ATL record of the losing account, it is not appended to the Territory_List_vod field on the winning ATL record
  • The ATL record for the losing account is deleted

Each ATL insert/update processes the following: 

  • A trigger takes the values found in the Territory_To_Add_vod and/or Territory_To_Drop_vod fields and add or remove the respective Territory values in the Territory_vod field. The Territory_To_Add/Drop_vod fields are cleared.
  • The trigger does not delete all ObjectTerritory2Association rows for the Account. Instead, the Trigger compares the before and after values of the Territory_vod field and ONLY process the differences found. This approach ensures that any Territory assignments that exist in the ObjectTerritory2Association object and happens to not be listed on the ATL record do not get deleted.
  • If a Territory happens to be listed in the Territory_vod field and the same Territory is placed in the Territory_To_Add/Drop_vod fields (effectively no change to the Territory_vod field), the trigger still re-attempts to add or drop the Territory

For example, Align initially inserts two Account assignments directly into CRM’s ObjectTerritory2Association table for Territory 101 and 102. No ATL record exists for the Account. The Account has two ObjectTerritory2Association rows where AssociationCause=Territory2Manual.

A CRM user aligned to Territory 103 uses Network Account Search or Global Account Search to upsert an ATL record. Only Territory 103 is listed in the Territory_vod field on the Account_Territory_Loader_vod object in CRM. Because the ATL_Mode_vod field is set to 1, ATL does not delete the initial two territories inserted by Align (101 and 102). The ATL processing approach processes only the single Territory listed in the ATL record—Territory 103.

Veeva CRM environments with Veeva Align managing the Territories and CRM containing Account assignments must have the Territory_Settings_vod field set to 1.

The Territory_Settings_vod field on the ATL_Mode__c object does not require a Veeva Align license; any Veeva CRM customer can use this setting.