Salesforce Territory Management and Programmatic Sharing

Did you know that just about all standard and custom objects can be shared to a territory? But what happens when you need to share an object record that is not included in the list of objects assigned by the Territory Management assignment rules? In this blog post, you’ll learn how to use manual territory access grants to share just about any standard and custom object in Salesforce to a territory. In addition, you’ll learn how that access extends through the territory and role hierarchies.

Did you know that just about all standard and custom objects can be shared to a territory? Salesforce Territory Management assignment rules can provide visibility to:

  • Accounts
  • Opportunities
  • Contacts
  • Cases
  • Child objects with a master-detail relationship to any of the previous objects

But what happens when you need to share an object record that is not included in the list of objects assigned by the Territory Management assignment rules? In this blog post, you’ll learn how to use manual territory access grants to share just about any standard and custom object in Salesforce to a territory. In addition, you’ll learn how that access extends through the territory and role hierarchies.

Introduction to Territory Management

For those of you who are unfamiliar with the Salesforce Territory Management feature, it’s an account sharing system that grants access to accounts based on the characteristics of those accounts. It enables your company to structure your Salesforce data and users in the same way that you structure your sales territories. Particularly if your organization has a private sharing model, you might need to grant users access to accounts based on criteria such as postal code, industry, revenue, or a custom field that is relevant to your business.

You might also need to generate forecasts for these diverse categories of accounts. The Salesforce Territory Management feature solves these business needs and provides a powerful solution for structuring your users, accounts, and their associated contacts, opportunities, and cases.

Key benefits of the Salesforce Territory Management feature include:

  • The ability to use account criteria to expand a private sharing model.
  • Support for complex and frequently changed sales organization structures.
  • Support for transferring users between territories, with the option to retain opportunities.
  • Multiple forecasts per user, based on territory membership.
  • Territory-based sales reports.

See Territory Management Overview. To decide if the Salesforce Territory Management feature is right for your organization, see the Territory Management Decision Guide.

Managing Sharing with Access Grants

We’ll refer to a share record that is associated to an object as an access grant. An AccountShare record sharing the ABC Furniture Co account to a territory would fall into this category, for example.

In the example below, we have shared the ABC Furniture Co account to the Territory and Subordinates group for 001-ISR-Warm leads.

 

 

Territory access grants can be created in a number of ways, including:

  • Through the account assignment rules
  • Manually
  • Programmatically

When you create a territory access grant using any of these methods, a share record is written to the object for the territory. In the following image, a query on the AccountShare object shows all the records the ABC Furniture Co account is shared to. The territory access grant from the previous example is highlighted.

 

 

Under the covers, the territory is represented by a record in the grouptable. For every territory in your territory hierarchy, two types of group records are created.

  • Territory
  • Territory and Subordinates

Each share record written for a territory specifies the Territory or Territory and Subordinates group for that territory. The group type controls how the access traverses the territory hierarchy. I’ll explain these group types in more detail in Understanding the Mechanisms Behind Hierarchy Visibility.

In the previous example, we shared to the Territory and Subordinates group for 001-ISR-Warm leads. The following query selects the groups for territory 001-ISR-Warm leads. Notice that the ID of the Territory and Subordinates group matches the UserOrGroupId in the AccountShare object.

 

 

No matter how the territory access grant is created, it always grants access to a territory group record. It is this group record that defines how much access is granted to the territory hierarchy. Because there are only two types of group records for each territory, there are only two types of access grants that define how visibility will roll up.

Before we explore how access is granted, let’s clarify the distinctions between the ways in which you can create access grants.

Creating Automatic Assignments with Territory Account Assignment Rules

Salesforce uses only account assignment rules to support the automatic assignment of object records to territories. Any time a territory is assigned using the account assignment rules, the systematic share is always written to the Territory Group.

You cannot manually or programmatically manipulate systematic object record shares to a territory–the only way to modify a systematic territory share is by using account assignment rules. While this strategy works perfectly for some customers, others need to assign object records outside of the Salesforce Territory Management feature or find that account assignment rules do not meet their requirements. In both cases, the customers can use manual territory access grants.

Let’s look at how manual territory access grants work.

Sharing Records with Manual Territory Access Grants

You can create manual territory access grants:

Unlike account assignment rules, which can share records to only the Territory group, manual territory access grants can share records to the Territory group or the Territory and Subordinates group. Shares associated to a standard object, such as a lead, or a custom object, such as order, can grant access in these two very different ways.

Understand that there is no distinction between a territory assigned to an account, lead, or custom object in terms of how the access is granted. The only distinction in terms of access is whether the share is written to the Territory group or the Territory and Subordinates group.

Also note that manual territory shares use the Manual row cause and are deleted when ownership changes on a record. As a result, they cannot be protected from other manual operations, such as users sharing with the manual share button.

For more information on protecting programmatic sharing, see Protecting Force.com Custom Sharing Code.

Understanding the Mechanisms Behind Hierarchy Visibility

In the previous example, we saw that the 001-ISR-Warm territory had two group object records behind the scenes. The types on each of those records were “Territory” and “TerritoryAndSubordinates.” Now let’s look at the visibility provided by each group.

The Territory group shares records to:

  • Members of the territory
  • Members of all its parent territories
  • Role managers of every territory member who is granted access

The Territory and Subordinates group shares records to:

  • Members of the territory
  • Members of all its parent territories
  • Members of all its subordinate territories
  • Role managers of every territory member who is granted access

The visibility spanning the territory members within the territory hierarchy might not have been surprising, but it’s important to remember that the role hierarchy grants managers the same access that their subordinates already have. It does this even for records that are granted access through the territory hierarchy.

When a record is shared to a territory, the access to that record is determined by the type of group–Territory or Territory and Subordinates–to which it was shared. The mechanism and the object to which the share was added make no difference.

Why is this important?

If you create a territory programmatic or manual share on any standard or custom object, the visibility will roll up both the territory hierarchy and the role hierarchy for each user within the territory hierarchy that is granted access.

Understanding How Territories Relate to Forecasting

To understand how territories tie to forecasting in the Salesforce Territory Management feature, we must first distinguish between assigning a record to a territory and sharing a record to a territory. You might have heard that opportunities in Salesforce can only have one territory, but this assertion is only partially true. While you can assign only a single territory to an opportunity, you can share an opportunity to as many territories as you wish.

In the following example, the “Generalist Farmers” territory has been assigned to the PF – US opportunity for ABC Furniture. The Patrick Finneran forecast includes only opportunities that are assigned to his territory. In this case, the opportunity is assigned and will be included in his forecast. Salesforce allows only one territory to be assigned to an opportunity to ensure that opportunities are not counted more than once in the forecast.

 

 

Now lets take a look at the manual sharing screen for the PF – US opportunity. Notice that the opportunity is shared to several additional territories.

 

 

Even though the visibility of this opportunity will roll up the territory hierarchy and role hierarchy for users in these territories, the forecast will only place this opportunity in the assigned territory.  This means that any additional programmatic or manual shares you add to an opportunity will not affect forecasting.

Summary

The Salesforce Territory Management feature supports sharing for all objects that support manual sharing, including both standard and custom objects. This flexibility allows custom and external engines to share just about any object using their territory assignment engine.

When any object in Salesforce is shared to a territory, the access granted to that object is based on the territory group the object was shared to, and traverses both the territory and role hierarchies. This process allows customers to architect the matrixed visibility of the Salesforce Territory Management feature’s territory hierarchy to any object supporting manual sharing.

Related Resources

About the Authors and CCE Technical Enablement

Sean Regan is a member of the Technical Enablement team within the salesforce.com Customer-Centric Engineering group. The team’s mission is to help customers understand how to implement technically sound salesforce.com solutions. Check out all of the resources that this team maintains on the Architect Core Resources page of Developer Force.

Published
March 13, 2013
Topics:

Leave your comments...

Salesforce Territory Management and Programmatic Sharing