Metadata API Developer’s Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

SharingRules

Represents the base container for sharing rules, which can be criteria-based, ownership-based, or territory-based. SharingRules enables you to share records with a set of users, using rules that specify the access level for the target user group.

This type extends the Metadata metadata type and inherits its fullName field. For more information, see “Sharing Rules Overview” in the Salesforce online help.

In API version 33.0 and later, retrieving, deleting, or deploying of all sharing rules in an organization is available . Wildcard support is also available. You can’t retrieve, delete, or deploy manual sharing rules or sharing rules by their type (owner, criteria-based, or territory).

Declarative Metadata File Suffix and Directory Location

In API version 33.0 and later, components are stored in the sharingRules folder and their file name matches the object name with the suffix .sharingRules. Criteria-based, owner-based, and territory-based sharing rules are all contained in a object.sharingRule file.

Prior to API version 33.0, SharingRules components are stored in their corresponding object directory and the file name matches the object name. For example, the accountSharingRules directory contains an Account.sharingRules file for account sharing rules. SharingRules for custom objects are stored in the customObjectSharingRules directory, which contains files with the .sharingRules extension such as ObjA__c.sharingRules, where ObjA refers to the developer name of a custom object type.

Version

SharingRules components are available in API version 24.0 and later, but these components are no longer available in API version 33.0 and later: AccountSharingRules, CampaignSharingRules, CaseSharingRules, ContactSharingRules, LeadSharingRules, OpportunitySharingRules, AccountTerritorySharingRules, CustomObjectSharingRules, UserSharingRules.

In API version 33.0 and later, use SharingCriteriaRule, SharingOwnerRule and SharingTerritoryRule.

Fields

The following information assumes that you are familiar with implementing sharing rules for standard objects and custom objects. For more information on these fields, see “Overview of Sharing Settings” in the Salesforce online help.

Field Field Type Description
sharingCriteriaRules SharingCriteriaRule[] An array of criteria-based sharing rules. Available in API version 33.0 and later.
sharingOwnerRules SharingOwnerRule[] An array of ownership-based sharing rules. Available in API version 33.0 and later.
sharingTerritoryRules SharingTerritoryRule[] An array of territory-based sharing rules. Available in API version 33.0 and later.

SharingCriteriaRule

Defines a criteria-based sharing rule. It extends SharingBaseRule and inherits all its fields. Available in API version 33.0 and later.

Field Field Type Description
booleanFilter string Advanced filter conditions that are specified for the sharing rule.
criteriaItems FilterItem[] An array of the boolean criteria (conditions) for the sharing rule.

SharingOwnerRule

Defines a ownership-based sharing rule. It extends SharingBaseRule and inherits all its fields. Available in API version 33.0 and later.

Field Field Type Description
sharedFrom SharedTo Required. Specifies the record owners.

SharingTerritoryRule

Defines a territory-based sharing rule. It extends SharingOwnerRule and inherits all its fields. Available in API version 33.0 and later.

AccountSharingRules

Represents the sharing rules for accounts. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules AccountCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules AccountOwnerSharingRule[] List that defines user membership-based rules.

CampaignSharingRules

Represents the sharing rules for campaigns. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules CampaignCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules CampaignOwnerSharingRule[] List that defines user membership-based rules.

CaseSharingRules

Represents the sharing rules for cases. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules CaseCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules CaseOwnerSharingRule[] List that defines user membership-based rules.

ContactSharingRules

Represents the sharing rules for contacts. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules ContactCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules ContactOwnerSharingRule[] List that defines user membership-based rules.

LeadSharingRules

Represents the sharing rules for leads. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules LeadCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules LeadOwnerSharingRule[] List that defines user membership-based rules.

OpportunitySharingRules

Represents the sharing rules for opportunities. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules OpportunityCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules OpportunityOwnerSharingRule[] List that defines user membership-based rules.

AccountTerritorySharingRules

Represents the sharing rules for account territories. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
rules AccountTerritorySharingRule[] List that defines user membership-based rules. The list of acceptable values for the sharedFrom fields are:
  • territory
  • territoryAndSubordinates

CustomObjectSharingRules

Represents the sharing rules for custom objects. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules CustomObjectCriteriaBasedSharingRule[] List that defines user criteria-based rules.
ownerRules CustomObjectOwnerSharingRule[] List that defines user membership-based rules.

UserSharingRules

Represents the sharing rules for users. With user sharing rules, you can share members of a group with members of another group. It extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.

Field Field Type Description
criteriaBasedRules UserCriteriaBasedSharingRule[] List that defines user criteria-based rules.
membershipRules UserMembershipSharingRule[] List that defines user membership-based rules.

Declarative Metadata Sample Definition

For retrieving sharing rules, see package.xml sample at Sharing Rules.

The following sample XML definition represents a criteria-based sharing rule in API version 33.0.

1<?xml version="1.0" encoding="UTF-8"?>
2<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
3    <sharingCriteriaRules>
4        <fullName>AccountCriteriaShareWithCEO</fullName>
5        <accessLevel>Edit</accessLevel>
6        <accountSettings>
7            <caseAccessLevel>Read</caseAccessLevel>
8            <contactAccessLevel>Edit</contactAccessLevel>
9            <opportunityAccessLevel>Edit</opportunityAccessLevel>
10        </accountSettings>
11        <criteriaItems>
12            <field>Name</field>
13            <operation>startsWith</operation>
14            <value>Test</value>
15        </criteriaItems>
16        <description>my account criteria rule description</description>
17        <label>AccountCriteriaShareWithCEO</label>
18        <sharedTo>
19            <role>CEO</role>
20        </sharedTo>
21    </sharingCriteriaRules>
22</SharingRules>

The following sample XML definition represents an ownership-based sharing rule in API version 33.0.

1<?xml version="1.0" encoding="UTF-8"?>
2<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
3    <sharingOwnerRules>
4        <fullName>MyCase</fullName>
5        <accessLevel>Edit</accessLevel>
6        <description>my case test owner sharing rule desc</description>
7        <label>MyCase</label>
8        <sharedFrom>
9            <role>COO</role>
10        </sharedFrom>
11        <sharedTo>
12            <role>CEO</role>
13        </sharedTo>
14    </sharingOwnerRules>
15</SharingRules>

The following sample XML definition represents a territory-based sharing rule in API version 33.0.

1<?xml version="1.0" encoding="UTF-8"?>
2<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
3    <sharingTerritoryRules>
4        <fullName>MyAccountTerritoryRule</fullName>
5        <accessLevel>Read</accessLevel>
6        <accountSettings>
7            <caseAccessLevel>None</caseAccessLevel>
8            <contactAccessLevel>Read</contactAccessLevel>
9            <opportunityAccessLevel>None</opportunityAccessLevel>
10        </accountSettings>
11        <description>MyAccountTerritoryRule desc</description>
12        <label>MyAccountTerritoryRule</label>
13        <sharedFrom>
14            <territory>My_territory</territory>
15        </sharedFrom>
16        <sharedTo>
17            <role>CEO</role>
18        </sharedTo>
19    </sharingTerritoryRules>
20</SharingRules>

The following is the definition of two account owner-based sharing rules in API version 32.0 and earlier. The file name corresponds to Account.sharingRules under the accountSharingRules directory. In this definition, ownerRules corresponds to AccountOwnerSharingRule.

1<?xml version="1.0" encoding="UTF-8"?>
2<AccountSharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
3    <ownerRules>
4        <fullName>G1Dev_G2New</fullName>
5        <sharedFrom>
6            <group>G1Dev</group>
7        </sharedFrom>
8        <sharedTo>
9            <group>G2New</group>
10        </sharedTo>
11        <accountAccessLevel>Read</caseAccessLevel>
12        <caseAccessLevel>None</caseAccessLevel>
13        <contactAccessLevel>Read</contactAccessLevel>
14        <name>G1Dev_G2New</name>
15        <opportunityAccessLevel>Edit</opportunityAccessLevel>
16    </ownerRules>
17    <ownerRules>
18        <fullName>G2New_R1New</fullName>
19        <sharedFrom>
20            <group>G2New</group>
21        </sharedFrom>
22        <sharedTo>
23            <roleAndSubordinates>R1New</roleAndSubordinates>
24        </sharedTo>
25        <accountAccessLevel>Edit</accountAccessLevel>
26        <caseAccessLevel>Read</caseAccessLevel>
27        <contactAccessLevel>Edit</contactAccessLevel>
28        <name>G2New_R1New</name>
29        <opportunityAccessLevel>None</opportunityAccessLevel>
30    </ownerRules>
31</AccountSharingRules>

The following is the definition of a user criteria-based sharing rule and a user membership-based sharing rule in API version 32.0 and earlier. The file name corresponds to User.sharingRules under the userSharingRules directory.

1<?xml version="1.0" encoding="UTF-8"?>
2<UserSharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
3    <criteriaBasedRules>
4        <fullName>shareUsers2</fullName>
5        <sharedTo>
6            <group>Asia_Division</group>
7        </sharedTo>
8        <criteriaItems>
9            <field>FirstName</field>
10            <operation>equals</operation>
11            <value>John</value>
12        </criteriaItems>
13        <name>shareUsers2</name>
14        <userAccessLevel>Read</userAccessLevel>
15    </criteriaBasedRules>
16    <membershipRules>
17        <fullName>shareUsers1</fullName>
18        <sharedTo>
19            <group>South_America_Division</group>
20        </sharedTo>
21        <sharedFrom>
22            <group>Asia_Division</group>
23        </sharedFrom>
24        <name>shareUsers1</name>
25        <userAccessLevel>Read</userAccessLevel>
26    </membershipRules>
27</UserSharingRules>

The following shows a sample package.xml file.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>ObjA__c.*</members>
5        <name>SharingCriteriaRule</name>
6    </types>
7    <types>
8        <members>ObjA__c.*</members>
9        <name>SharingOwnerRule</name>
10    </types>
11    <version>33.0</version>
12</Package>