ObjectLinkingSettings Metadata Type Guide

Architectural Overview#

ObjectLinkingSettings governs the automated and recommended association behaviors between real-time interaction channels—such as Service Cloud Voice calls, In-App and Web Messaging sessions, and Live Chat transcripts—and core CRM business entities (such as Contact, Lead, Account, and Case).

In modern omnichannel contact centers, agents waste critical handling seconds manually searching and linking caller phone numbers or chat identifiers to CRM records. Deploying ObjectLinkingSettings activates platform heuristics and declarative matching rules that automatically attach communication sessions to existing customer records upon channel connection.

Directory and File Conventions#

ObjectLinkingSettings is configured as a singleton settings type in the settings/ directory.

Key Metadata Fields#

The XML schema for ObjectLinkingSettings controls platform linking behaviors:

Declarative XML and Package Manifest Examples#

A standard production settings file enabling automated object linking for contact center workflows:

<?xml version="1.0" encoding="UTF-8"?>
<ObjectLinkingSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableAutomatedLinking>true</enableAutomatedLinking>
    <enableObjectLinking>true</enableObjectLinking>
</ObjectLinkingSettings>

Scratch Org Configuration (config/project-scratch-def.json)#

To enable object linking in a Service Cloud scratch org:

{
  "orgName": "Service Cloud Voice Scratch Org",
  "edition": "Enterprise",
  "features": ["ServiceCloudVoice", "LiveMessage"],
  "settings": {
    "objectLinkingSettings": {
      "enableObjectLinking": true,
      "enableAutomatedLinking": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage ObjectLinkingSettings using the Salesforce CLI:

# Retrieve Object Linking settings
sf project retrieve start --metadata Settings:ObjectLinking

# Deploy Object Linking settings
sf project deploy start --metadata Settings:ObjectLinking

Architect Best Practices and Gotchas#

• Ambiguous Match Strategy: When enableAutomatedLinking is active, multiple records sharing the same phone number or email will suppress auto-linking and present a candidate picklist to the agent to avoid corrupting relationship data.
• Service Cloud Feature Licensing: In scratch orgs or sandboxes, deploying ObjectLinkingSettings will fail if the org lacks prerequisite features like LiveMessage, ServiceCloudVoice, or Omni-Channel licensing.
• Downstream Automation Sequencing: Ensure Record-Triggered Flows on VoiceCall or MessagingSession anticipate that ContactId or CaseId may be populated asynchronously immediately following session creation.

Frequently asked questions

What is the role of ObjectLinkingSettings in Service Cloud?

ObjectLinkingSettings controls automated linking rules that associate incoming voice calls and messaging sessions with Contacts, Leads, or Cases.

Does ObjectLinkingSettings support automated record association?

Yes. It provides configuration switches to automatically associate interactions with identified customer records upon channel connection.

Where is ObjectLinkingSettings stored in SFDX projects?

It is stored in force-app/main/default/settings/ObjectLinking.settings-meta.xml and retrieved as Settings:ObjectLinking.