RecordAggregationDefinition Metadata in SFDX

Architectural Overview#

RecordAggregationDefinition represents a declarative framework for rolling up, summing, and aggregating metrics across multi-tiered object relationships. Standard Salesforce Roll-Up Summary fields are strictly constrained to Master-Detail relationships on standard or custom objects, with hard org limits per object. In contrast, RecordAggregationDefinition empowers enterprise and industry solutions (such as Financial Services Cloud, Health Cloud, and Consumer Goods) to aggregate related transactions, financial holdings, or claims across lookup relationships and complex junction entities.

From an architectural standpoint, RecordAggregationDefinition abstracts the aggregation pipeline into metadata. It specifies source objects, aggregation criteria, target destination fields, and calculation frequencies (real-time, asynchronous, or scheduled batch), avoiding custom Apex triggers and high-risk trigger recursion.

Directory and File Conventions#

RecordAggregationDefinition instances are maintained as distinct XML artifacts inside the recordAggregationDefinitions directory.

Key Metadata Fields#

The definition encapsulates source entity mapping, filter conditions, and calculation target configurations.

Declarative XML and Package Manifest Examples#

The following sample defines an aggregation rule rolling up total portfolio balances from individual financial accounts up to a client household profile:

<?xml version="1.0" encoding="UTF-8"?>
<RecordAggregationDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Household Total Balance</masterLabel>
    <developerName>Household_Total_Balance</developerName>
    <sourceObject>FinServ__FinancialAccount__c</sourceObject>
    <targetObject>Account</targetObject>
    <aggregateField>FinServ__Balance__c</aggregateField>
    <targetField>Total_Portfolio_Balance__c</targetField>
    <operation>Sum</operation>
    <status>Active</status>
    <filterCriteria>FinServ__Status__c = 'Open' AND FinServ__RecordTypeName__c != 'Liability'</filterCriteria>
</RecordAggregationDefinition>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy aggregation definitions using Salesforce CLI:

# Retrieve all aggregation definitions
sf project retrieve start --metadata RecordAggregationDefinition

# Deploy a specific definition along with custom field dependencies
sf project deploy start --metadata "RecordAggregationDefinition:Household_Total_Balance,CustomField:Account.Total_Portfolio_Balance__c"

# Validate deployment against a sandbox
sf project deploy validate --metadata RecordAggregationDefinition:Household_Total_Balance

Architect Best Practices and Gotchas#

• Dependency Sequencing: The target custom field and source custom fields must exist in the target org before deploying RecordAggregationDefinition. Include both the CustomField components and the aggregation definition in the same deployment changeset.
• Large Data Volumes (LDV): When aggregating millions of records, evaluate whether recalculations run synchronously during DML or asynchronously via platform rollup services. Ensure source fields utilized in filterCriteria are indexed to prevent full-table table scans.
• Status Gating: Deploy definitions in Draft status first when introducing structural schema modifications, then toggle to Active after validating that batch calculation jobs finish without errors.

Frequently asked questions

What is the primary role of RecordAggregationDefinition in Salesforce?

It defines declarative calculation and rollup logic across related objects, aggregating high-volume financial or transactional data onto parent records without custom code.

Where is RecordAggregationDefinition stored in the project structure?

It is stored in the recordAggregationDefinitions folder with the file extension .recordAggregationDefinition-meta.xml.

Does RecordAggregationDefinition execute synchronously or asynchronously?

Aggregation execution typically runs asynchronously or via scheduled calculation engines to prevent transaction governor limit exhaustion during high-volume data operations.

What industry clouds use RecordAggregationDefinition extensively?

It is widely utilized in Financial Services Cloud, Health Cloud, and Public Sector Solutions for householding, member totals, and policy metrics.