Create a Branch Management Scoping Rule Using the Metadata API

Create a scoping rule that filters account records based on a banker’s branch location. This example uses the branch management data model included in Financial Services Cloud and the RestrictionRule Metadata API type.

Available in: Lightning Experience in Performance and Unlimited Editions

User Permissions Needed
To create and manage scoping rules:	Manage Sharing
To view scoping rules:	View Setup & Configuration AND View Restriction and Scoping Rules

This example uses the SOQL operator in its recordFilter to identify the accounts that match a retail banker’s branch location. Check out the Branch Management data model to understand the objects used in this example and how they relate to each other.

Use the RestrictionRule type to create and manage both restriction rules and scoping rules. Set up the package.xml manifest file and your directory.

Example 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>*</members>
5    <name>RestrictionRule</name>
6  </types>
7  <version>56.0</version>
8</Package>

Example directory:

1myPackage/package.xml
2myPackage/restrictionRules
3myPackage/restrictionRules/Rule1.rule
4myPackage/restrictionRules/Rule2.rule

Include all required fields.

In this example, we used these values.

1<?xml version="1.0" encoding="UTF-8"?>
2<RestrictionRule xmlns="http://soap.sforce.com/2006/04/metadata">
3  <active>true</active>
4  <description>Scoping rule where users can scope account records by the user’s current
5branch</description>
6  <enforcementType>Scoping</enforcementType>
7  <masterLabel>BranchRuleOnAccount</masterLabel>
8  <recordFilter>SOQL(Id, SELECT AccountId FROM BranchUnitCustomer USING SCOPE
9EVERYTHING WHERE BranchUnitId IN(SELECT CurrentBranchId From Banker WHERE
10UserOrContactId = $User.Id))</recordFilter>
11  <targetEntity>Account</targetEntity>
12  <userCriteria>$User.IsActive = true</userCriteria>
13  <version>1</version>
14</RestrictionRule>

This example also uses objects from the Branch Management data model and sets a scoping rule that shows users lead records related to the user’s current branch location.

1<?xml version="1.0" encoding="UTF-8"?>
2<RestrictionRule xmlns="http://soap.sforce.com/2006/04/metadata">
3  <active>true</active>
4  <description>Scoping rule where users can scope lead records by their current
5branch</description>
6  <enforcementType>Scoping</enforcementType>
7  <masterLabel>BranchRuleOnLead</masterLabel>
8  <recordFilter>SOQL(Id, SELECT RelatedRecordId FROM BranchUnitRelatedRecord USING SCOPE
9EVERYTHING WHERE BranchUnitId IN(SELECT CurrentBranchId From Banker WHERE
10UserOrContactId = $User.Id))</recordFilter>
11  <targetEntity>Lead</targetEntity>
12  <userCriteria>$User.IsActive = true</userCriteria>
13  <version>1</version>
14</RestrictionRule>

To create a similar scoping rule for a different object, adjust the targetEntity field to include case, contact, or another supported standard or custom object.

Zip your directory, and deploy your changes. For more information, see Deploying and Retrieving Metadata in the Metadata API Developer Guide.
Let’s take a closer look at the Branch Rule On Account example’s SOQL operator.
SOQL(Id, SELECT AccountId FROM BranchUnitCustomer USING SCOPE EVERYTHING WHERE BranchUnitId IN(SELECT CurrentBranchId From Banker WHERE UserOrContactId = $User.Id))
- The SOQL statement takes the Id from the account object, which is the target entity whose records the scoping rule filters, and selects AccountId from the BranchUnitCustomer object.
- The where clause gets the BranchUnitId, which is a unique identifier of each branch, from a nested query. The nested query finds each banker’s current branch from the Banker object by matching the UserOrContactId to the currently logged-in user.
When writing scoping rules using SOQL, follow these guidelines.
- In SOQL operators, the SOQL query object and the scoping rule target entity can’t be the same object. In this example, the SOQL query object is BranchUnitCustomer and the scoping rule object, called the targetEntity, is account.
- In the SOQL type RecordCriteria, the left operand must query a single ID (primary key) or reference (foreign key) field. In this example, the left operand is a field on the target entity called Id.
For more tips about writing scoping rules using a performant SOQL operator, see Scoping Rules Considerations. The SOQL operator is supported for scoping rules only.

Scoping Rules Developer Guide

Create a Branch Management Scoping Rule Using the Metadata API

See Also