RelatedRecordAssocCriteria Metadata in SFDX

Architectural Overview#

RelatedRecordAssocCriteria governs the declarative intelligence engine responsible for automatically associating inbound records and digital interactions (such as Service Cloud Voice calls, digital messaging sessions, and inbound document intake) with existing core CRM entities (such as Contacts, Accounts, or Cases).

In high-volume omnichannel contact centers, manual record lookup introduces cognitive friction, inflates Average Handle Time (AHT), and leads to duplicate record creation. RelatedRecordAssocCriteria establishes deterministic matching logic that evaluates attributes from the incoming interaction payload (such as caller phone number, customer email, or policy identifier) against CRM database records, establishing relationship links instantly as the interaction initiates.

Directory and File Conventions#

RelatedRecordAssocCriteria components are maintained within the relatedRecordAssocCriteria directory.

Key Metadata Fields#

The definition outlines source and target object types, matching expressions, and fallback strategies.

Declarative XML and Package Manifest Examples#

The following example configures an automated matching rule linking inbound voice calls to Contacts based on matching mobile phone numbers:

<?xml version="1.0" encoding="UTF-8"?>
<RelatedRecordAssocCriteria xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>VoiceCall Contact Match</masterLabel>
    <developerName>VoiceCall_Contact_Match</developerName>
    <sourceObject>VoiceCall</sourceObject>
    <targetObject>Contact</targetObject>
    <matchingCriteria>VoiceCall.FromPhoneNumber = Contact.MobilePhone OR VoiceCall.FromPhoneNumber = Contact.Phone</matchingCriteria>
    <status>Active</status>
    <description>Automatically associates inbound voice calls with matching Contact records via caller ID.</description>
</RelatedRecordAssocCriteria>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage RelatedRecordAssocCriteria definitions using the Salesforce CLI:

# Retrieve all RelatedRecordAssocCriteria definitions
sf project retrieve start --metadata RelatedRecordAssocCriteria

# Deploy a specific matching criteria component
sf project deploy start --source-dir force-app/main/default/relatedRecordAssocCriteria/VoiceCall_Contact_Match.relatedRecordAssocCriteria-meta.xml

# Validate the deployment in a target scratch org
sf project deploy validate --metadata RelatedRecordAssocCriteria:VoiceCall_Contact_Match

Architect Best Practices and Gotchas#

• Indexed Matching Fields: Ensure fields referenced in matchingCriteria (e.g., Phone, Email, ExternalId__c) are indexed in the target object schema. High-volume call centers performing unindexed queries on large Contact tables will suffer latency bottlenecks.
• Handling Ambiguity: If phone numbers are shared across multiple family members (e.g., a shared home landline), automated linking could attach calls to the wrong person. Pair declarative criteria with an agent confirmation screen in Flow to resolve ambiguous matches.
• Object Availability: VoiceCall and MessagingSession objects require Service Cloud Voice or Digital Engagement licenses. Verify that target sandboxes have corresponding features enabled prior to deploying criteria files.

Frequently asked questions

What is the primary role of RelatedRecordAssocCriteria?

It defines declarative matching logic to automatically evaluate and associate incoming interaction records, such as Voice Calls or Messaging sessions, with parent CRM records.

Where is RelatedRecordAssocCriteria located in the SFDX project?

It is located in the relatedRecordAssocCriteria directory with the .relatedRecordAssocCriteria-meta.xml file extension.

Can RelatedRecordAssocCriteria match records across multiple fields?

Yes, it supports complex criteria matching using multiple fields, filter operators, and fallback rules to find unique record candidates.

What happens if multiple matching records are identified?

Depending on the matching strategy configured, the association engine can link to the most recently modified record or prompt the user to manually select the correct record.