EmployeeUserSettings Metadata in SFDX

Architectural Overview#

EmployeeUserSettings is an enterprise settings metadata type that bridges human resources data management with Salesforce identity and access management (IAM). It governs how standard Employee object records synchronize changes and automatically provision or update standard User accounts across the platform.

In modern enterprise architectures, human capital management (HCM) systems like Workday or SAP SuccessFactors replicate worker records into the Salesforce Employee standard object. EmployeeUserSettings provides declarative controls ensuring that worker onboarding, role changes, contact updates, and terminations cascade cleanly into Salesforce user accounts without bespoke batch Apex triggers.

Directory and File Conventions#

EmployeeUserSettings follows standard Salesforce settings conventions. It is saved in the settings directory using the EmployeeUser name prefix.

Key Metadata Fields#

The EmployeeUserSettings XML structure contains settings that regulate provisioning rules and automatic synchronization:

Declarative XML and Package Manifest Examples#

Below is an example declarative settings XML configuration:

<?xml version="1.0" encoding="UTF-8"?>
<EmployeeUserSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableAutoUserProvisioning>false</enableAutoUserProvisioning>
    <enableEmployeeUserSync>true</enableEmployeeUserSync>
</EmployeeUserSettings>

Manifest Definition (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy EmployeeUserSettings using the sf CLI:

# Retrieve EmployeeUser settings
sf project retrieve start --metadata Settings:EmployeeUser

# Deploy EmployeeUser settings
sf project deploy start --metadata Settings:EmployeeUser

Architect Best Practices and Gotchas#

• Identity Lifecycle Integrity: Avoid enabling enableAutoUserProvisioning without strict email address validation on the inbound HCM data feed to prevent duplicate user account generation.
• Deactivation Handling: When an employee record is marked inactive or terminated, verify that your synchronization settings downgrade user access or deactivate the corresponding User record in compliance with SOC2 access governance.
• Profile Dependencies: If profileName is specified in the settings metadata, the referenced Profile must exist in the target org prior to deployment.

Frequently asked questions

What is the purpose of EmployeeUserSettings in Salesforce?

It controls synchronization and user provisioning between the standard Employee object and Salesforce User records for internal HR workflows.

How is EmployeeUserSettings organized in source format?

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

Does EmployeeUserSettings require Work.com or HR Service Center?

It is commonly used with Work.com and HR Service Center, but applies anywhere the standard Employee data model integrates with core Salesforce Users.