PresenceDeclineReason Metadata in SFDX

Architectural Overview#

In mission-critical contact centers powered by Service Cloud Omni-Channel, routing telemetry is crucial for operational excellence. When customer inquiries (Cases, Chats, Voice Calls, Messaging Sessions) are pushed to available agents, agents may occasionally decline work due to shifting priorities, insufficient skill sets, or imminent end-of-shift transitions.

The PresenceDeclineReason metadata type defines standardized decline reasons presented in the Omni-Channel utility widget. When an agent clicks “Decline”, they must select an architect-approved reason.

Telemetry captured via PresenceDeclineReason is logged to AgentWork records, empowering Workforce Management (WFM) leaders to pinpoint routing imbalances, identify training gaps, and optimize staffing schedules.

Directory and File Conventions#

In SFDX source projects, PresenceDeclineReason metadata files are organized in the presenceDeclineReasons/ directory:

Key Metadata Fields#

The XML definition of PresenceDeclineReason consists of user-facing labels:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition for an agent end-of-shift decline reason:

<?xml version="1.0" encoding="UTF-8"?>
<PresenceDeclineReason xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Shift Ending / Handover in Progress</label>
</PresenceDeclineReason>

Paired Presence User Configuration Reference#

Decline reasons must be added to PresenceUserConfig to be visible to agents:

<?xml version="1.0" encoding="UTF-8"?>
<PresenceUserConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <capacity>5</capacity>
    <declineReasons>
        <declineReason>Shift_Ending</declineReason>
    </declineReasons>
    <enableAutoAccept>false</enableAutoAccept>
    <enableDecline>true</enableDecline>
    <enableDeclineReason>true</enableDeclineReason>
    <masterLabel>Tier 2 Support Config</masterLabel>
</PresenceUserConfig>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage PresenceDeclineReason metadata with the Salesforce CLI:

# Retrieve all presence decline reasons
sf project retrieve start --metadata PresenceDeclineReason

# Deploy specific decline reason with presence configurations
sf project deploy start --metadata "PresenceDeclineReason:Shift_Ending" --metadata "PresenceUserConfig:Tier_2_Support_Config"

# Validate deployment into sandbox environment
sf project deploy validate --metadata PresenceDeclineReason

Architect Best Practices and Gotchas#

• Presence Configuration Linking: Deploying a PresenceDeclineReason without binding it to active PresenceUserConfig definitions leaves the reason dormant; agents will not see it in the console.
• Reporting Dependencies on AgentWork: Before renaming or deleting a decline reason, review SOQL queries and CRM Analytics dashboards querying AgentWork.DeclineReason to prevent reporting interruptions.
• Limit Decline Reasons for Speed: Provide 4 to 6 clear, actionable decline reasons. Presenting excessive choices slows agent response times and inflates customer wait queues.

Frequently asked questions

What is the function of PresenceDeclineReason in Omni-Channel?

It provides predefined, selectable reasons when an agent declines a routed work item, capturing analytics for supervisor dashboards and WFM reports.

Where are PresenceDeclineReason files stored in an SFDX directory?

They reside in force-app/main/default/presenceDeclineReasons/ with the .presenceDeclineReason-meta.xml suffix.

How is PresenceDeclineReason associated with service agents?

Decline reasons are referenced in PresenceUserConfig metadata, which is assigned to users or profiles.

Does declining a work item affect agent capacity in Omni-Channel?

No, declining releases the work item from the agent's queue and immediately re-routes it to the next eligible agent or fallback queue.