Restriction Rules

Restriction Rules

This skill activates when record access has to be taken away from users who already hold it — a compliance carve-out, a team-versus-team data wall, or a "reps see only the tasks they own" requirement. Every other layer in the sharing model grants; the restriction rule is the one that subtracts. It is also the layer most often oversold, so a large part of this skill is being precise about what it does not reach.

Before Starting

Gather this before designing anything:

• Is the object even eligible? For enforcementType Restrict, targetEntity accepts Contract, Event, Quote, Task, TimeSheet, TimeSheetEntry, plus custom objects and external objects. Account, Opportunity, Case, Contact, and Lead are not on that list. If the request is "hide some Opportunities," the answer is not a restriction rule.
• Can the requirement be written as a single EQUALS test? The criteria language supports only the = operator. There is no AND, no OR, no !=, no formula. If the requirement needs two conditions joined, it either gets pushed into a single roll-up-style field on the record or it is not a restriction rule.
• Who holds View All / Modify All on this object, and which code runs in system mode? Both are documented bypasses. Enumerate them before you promise anyone the data is hidden, not after the audit finds it.
• What edition is the org? Enterprise and Developer allow up to two active restriction rules per object; Performance and Unlimited allow up to five. The ceiling counts active rules. Scoping rules have their own separate ceiling (two per object in Developer, five in Performance and Unlimited — the guide states no Enterprise number), so the two kinds do not share a budget. What they do share is the per-user constraint: only one restriction or scoping rule may apply to any given user on a given object.

Core Concepts

Subtraction, not a grant

A restriction rule never gives anyone access. Salesforce states it plainly: "When a restriction rule is applied to a user, the records that the user is granted access to via org-wide defaults, sharing rules, and other sharing mechanisms are filtered by criteria that you specify." The rule runs after the sharing model has produced a result set and removes rows from it. If OWD, the role hierarchy, and sharing rules never granted the record in the first place, the restriction rule is irrelevant to that record.

The practical consequence is that a restriction rule cannot fix an over-permissive OWD. It hides the symptom on a fixed list of surfaces while the underlying grant stays intact in the sharing tables, where anything that reads outside those surfaces still finds it.

Where the filter is enforced — and where it is not

Salesforce enumerates the enforcement surfaces: Links, List Views, Lookups, Records, Related Lists, Reports, Search, SOQL, SOSL. That is a wide net and it covers the API, which is why restriction rules are genuinely more than a UI decoration.

It is not, however, an absolute boundary. Salesforce documents eight gaps — seven where a restricted user still reaches filtered data, and one where the platform reports as though the rule did not exist. Quote them to any stakeholder who asks for a compliance guarantee:

Call a restriction rule a run-time visibility filter with eight documented gaps, and design accordingly. If the requirement must survive an integration user with Modify All Data or a without sharing class, the answer is a tighter OWD plus removal of whichever sharing layer granted the access — see admin/sharing-and-visibility. references/gotchas.md works through what each gap looks like in production.

The criteria language is one EQUALS test on each side

userCriteria picks the audience; recordFilter picks what that audience keeps. Both are strings, both are limited to =, and both are evaluated at query time.

Working recordFilter / userCriteria pairs straight from the Salesforce examples:

The metadata shape

RestrictionRule is one metadata type serving both mechanisms: suffix .rule, directory restrictionRules, available in API version 52.0 and later. enforcementType decides which mechanism you get.

<!-- restrictionRules/Tasks_You_Own.rule -->
<?xml version="1.0" encoding="UTF-8"?>
<RestrictionRule xmlns="http://soap.sforce.com/2006/04/metadata">
    <active>true</active>
    <description>Allows users with a specific profile to see only tasks that they own.</description>
    <enforcementType>Restrict</enforcementType>
    <masterLabel>Tasks You Own</masterLabel>
    <recordFilter>OwnerId = $User.Id</recordFilter>
    <targetEntity>Task</targetEntity>
    <userCriteria>$User.ProfileId = '00exxxxxxxxxxxx'</userCriteria>
    <version>1</version>
</RestrictionRule>

Managing these rules requires the Manage Sharing permission (view, create, update, delete). The View Restriction and Scoping Rules permission grants read-only visibility through the API. The Tooling API exposes the same object with IsActive, DeveloperName, RecordFilter, TargetEntity, UserCriteria and EnforcementType fields at POST /services/data/vXX.0/tooling/sobjects/RestrictionRule.

Common Patterns

Pattern: own-records-only on Task or Event

When to use: activity data carries client detail that must not spread laterally across a shared services team, and the org's activity sharing setting is too coarse to express it.

How it works: set userCriteria to the profile that must be constrained and recordFilter to OwnerId = $User.Id. Every other layer keeps working — managers above the user in the hierarchy are unaffected unless a second rule targets them too, because a rule only applies to users its userCriteria matches.

Why not tighten activity sharing instead: activity access settings are org-wide and blunt; the restriction rule constrains exactly one profile and leaves everyone else on the existing model.

What breaks: the Open Activities and Activity History related lists behave badly under restriction rules — Salesforce recommends the Activity Timeline instead, because those related lists can show "fewer than 50 records ... when more activities exist that the user has access to." Plan the page layout change with the rule, not after it.

Pattern: department-scoped Contract visibility for external users

When to use: Experience Cloud users on a high-volume licence should see only the contracts for their own department, and sharing sets are granting a wider set.

How it works: userCriteria of $User.UserType = 'CSPLitePortal' selects the audience; recordFilter of Department__c = $User.Department keeps only the matching contracts. The custom Department__c field on the contract has to be populated by automation before the rule is switched on — an unpopulated field is a blank value on the record side, and blanks behave unpredictably in record criteria.

Why not fix it in the sharing set: sharing sets grant along a contact/account relationship, which is a different axis from department. The restriction rule filters the result of the sharing set without rewriting it.

Pattern: staged rollout with active false

When to use: any first restriction rule on a populated object.

How it works: deploy with <active>false</active>, then measure the recordFilter as a query against the target object using an API client — Salesforce's own guidance is to "take the record criteria to your API client of choice and run the query," and to "add three to five percent overhead to the record filter's performance" for objects with large data volumes. Activate only when the returned row set matches the intended survivor list and the query time is acceptable.

Why not activate directly: an over-tight recordFilter removes rows silently. Nothing errors, no one is notified, and the first signal is a user reporting that a record they worked yesterday has disappeared.

Decision Guidance

Recommended Workflow

1. Confirm eligibility and edition. Check the object against the supported targetEntity list and count the rules already active on it. If the object is ineligible or the ceiling is reached, stop and route the requirement to admin/sharing-and-visibility instead of forcing a rule.
2. Write the bypass inventory before writing the rule. List every user and permission set granting View All / View All Data / Modify All / Modify All Data on the object, every Apex class and integration that touches it in system mode, and whether calendars, Chatter publisher posts, or search shortcuts are in scope. Hand this list to whoever asked for the restriction and get their agreement in writing that the residual paths are acceptable.
3. Express the requirement as two EQUALS tests. One on a $User field for userCriteria, one on a record field for recordFilter. Use 15-character Ids, name the object type when traversing Owner (Owner:User.…), and confirm the record field is populated on every row that must survive.
4. Deploy inactive and measure. Ship the .rule file with <active>false</active>, then run the recordFilter as a query against the target object and compare the returned rows against the intended survivor list. Budget three to five percent overhead on large-data-volume objects.
5. Activate and test as the restricted user. Log in as a user whose userCriteria matches and verify the filter in the record UI, in a report, in a related list, and in a SOQL call. Then verify a non-matching user is unaffected. Do not use UserRecordAccess as the test — it does not account for restriction rules.
6. Run the checker and promote. python3 skills/admin/restriction-rules/scripts/check_restriction_rules.py --manifest-dir <metadata-dir> flags unsupported operators, 18-character Ids, ineligible target objects, bare Owner. traversals, an enforcementType of FieldRestrict, and active-rule counts over the edition ceiling for that enforcement type. Promote by change set or unlocked package and remap any org-specific Ids in recordFilter and userCriteria for the target org.

Review Checklist

• targetEntity is on the supported list for enforcementType Restrict
• Active Restrict rule count on this object is within the edition ceiling (2 for Enterprise/Developer, 5 for Performance/Unlimited); active Scoping rules are counted separately against their own ceiling
• No user matches the userCriteria of more than one active restriction or scoping rule on this object
• recordFilter and userCriteria each contain exactly one = and no AND, OR, or formula
• Any Id literal is 15 characters, and every org-specific Id is on the deployment remap list
• enforcementType is Restrict (or deliberately Scoping) — never FieldRestrict, which the reference marks "Don't use."
• No custom picklist value referenced by the rule is scheduled for deletion — deleting it stops the rule working as intended
• Owner traversals use the Owner:User. object-type form, and no expression crosses more than one lookup level from the targetEntity
• The record field used in recordFilter is populated on every record intended to survive — no blanks or nulls
• The bypass inventory is written down and signed off, including View All / Modify All holders and system-mode code paths
• Child objects have their own rule where the requirement extends to them
• Activity related lists have been replaced with the Activity Timeline on any layout for a restricted Task or Event
• The rule was tested as a matching user and as a non-matching user, in UI, report, and SOQL
• Access-audit tooling built on UserRecordAccess has been annotated as not restriction-rule aware

Salesforce-Specific Gotchas

Short form; the mechanics and recovery steps for each are in references/gotchas.md.

1. A rule is not a security boundary — eight documented paths still reach filtered records, and two of them (system mode, Modify All Data) are exactly the paths an integration takes.
2. UserRecordAccess lies about it — the object that access-audit tooling is usually built on returns the pre-restriction answer.
3. Only EQUALS exists — no AND, OR, or formula, so multi-condition requirements have to be precomputed into a field before the rule can express them.
4. 18-character Ids are the wrong length here — record criteria wants 15, and the common source of an Id (a copy out of a browser URL or a Data Loader export) is often 18.
5. Owner. fails, Owner:User. works — the Owner reference needs an explicit object type, which is unlike every other dot-notation traversal on the platform.
6. Restricting a parent does not restrict its children — each object needs its own rule.
7. Activity related lists undercount — Open Activities and Activity History can show fewer than 50 rows when more exist that the user can access.

Output Artifacts

Related Skills

• admin/scoping-rules — the sibling enforcementType; filters the default record set in list views and reports without changing access
• admin/sharing-and-visibility — the grant side of the model; go here when the correct fix is a tighter OWD rather than a filter on top
• admin/sharing-rules — the layer that most often granted the access a restriction rule is being asked to take back
• security/record-access-troubleshooting — for tracing one named user against one named record; note the UserRecordAccess caveat above before trusting its output
• apex/apex-security-patterns — user mode versus system mode in Apex, which decides whether the rule applies to your code at all