AccountRelationshipShareRule Metadata Type in SFDX

Architectural Overview#

The AccountRelationshipShareRule metadata type configures Account Relationship Data Sharing rules in Salesforce. In multi-tier B2B distribution models, franchise networks, and Experience Cloud Partner Central implementations, a distributor (AccountFrom) often needs visibility into Opportunities, Cases, Orders, or custom objects owned by or associated with a dealer (AccountTo), without merging the two Accounts or writing brittle Apex managed sharing triggers.

When an architect defines an AccountRelationshipShareRule for a specific AccountRelationship.Type picklist value, Salesforce’s native sharing engine automatically calculates and maintains record shares whenever an AccountRelationship record of that type is created, modified, or deleted.

Directory and File Conventions#

In SFDX source format (apiVersion 68.0), AccountRelationshipShareRule components are stored in the accountRelationshipShareRules directory.

Key Metadata Fields#

The AccountRelationshipShareRule XML schema exposes the following core elements:

Declarative XML and Package Manifest Examples#

The following example shares dealer Opportunity records (Read access) with the parent distributor whenever an AccountRelationship record of type Distributor_Dealer connects the two Accounts:

<?xml version="1.0" encoding="UTF-8"?>
<AccountRelationshipShareRule xmlns="http://soap.sforce.com/2006/04/metadata">
    <accessLevel>Read</accessLevel>
    <accountToCriteriaField>AccountId</accountToCriteriaField>
    <description>Grants distributor partner users read access to dealer opportunities.</description>
    <entityType>Opportunity</entityType>
    <masterLabel>Distributor Opportunity Read Rule</masterLabel>
    <type>Distributor_Dealer</type>
</AccountRelationshipShareRule>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Distributor_Opportunity_Read</members>
        <name>AccountRelationshipShareRule</name>
    </types>
    <types>
        <members>Account</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

SOQL Queries and CLI Automation#

You can query configured AccountRelationshipShareRule records via SOQL or retrieve and deploy them via Salesforce CLI:

SELECT Id, DeveloperName, MasterLabel, EntityType,
       AccessLevel, AccountToCriteriaField, Type
FROM AccountRelationshipShareRule
ORDER BY EntityType ASC, DeveloperName ASC

# Retrieve all AccountRelationshipShareRule components
sf project retrieve start --metadata "AccountRelationshipShareRule:*"

# Deploy a specific AccountRelationshipShareRule
sf project deploy start --metadata AccountRelationshipShareRule:Distributor_Opportunity_Read

Architect Best Practices and Gotchas#

• Picklist Dependency on AccountRelationship.Type: The <type> value in AccountRelationshipShareRule must exist as an active picklist value on AccountRelationship.Type. Deploy the AccountRelationship custom field picklist values before or alongside the share rule.
• Prerequisite AccountSettings: Ensure <enableAccountRelationships>true</enableAccountRelationships> is deployed in Account.settings-meta.xml before deploying AccountRelationshipShareRule.
• Sharing Table Skew: Connecting a single top-level Holding Account (AccountFrom) to thousands of high-volume dealer Accounts (AccountTo) via AccountRelationship can trigger heavy sharing recalculation times. Monitor sharing calculation latency alongside standard SharingRules.

Frequently asked questions

What is the purpose of AccountRelationshipShareRule in Salesforce?

It defines the object-level access (Read or Edit) granted from one Account to another Account when they are connected via an AccountRelationship record.

What setting must be enabled before deploying AccountRelationshipShareRule?

Account Relationships must be enabled in AccountSettings via the enableAccountRelationships flag before you can deploy AccountRelationshipShareRule metadata.

How does AccountRelationshipShareRule differ from standard SharingRules?

Standard SharingRules share records with roles or public groups based on ownership or criteria, whereas AccountRelationshipShareRule dynamically shares records across Account hierarchies and B2B partner networks using AccountRelationship junction records.

Where are AccountRelationshipShareRule files stored in SFDX?

They are stored in force-app/main/default/accountRelationshipShareRules with the .accountRelationshipShareRule-meta.xml suffix.