MobileSettings Metadata Type in Salesforce DX

Architectural Overview#

The MobileSettings metadata type represents organization-wide configurations and operational preferences for the Salesforce Mobile application. In distributed enterprise operations—such as field sales, field service, and logistics—reliable mobile access in environments with intermittent or zero internet connectivity is essential to maintain business continuity.

MobileSettings manages core mobile caching and data persistence capabilities. It enables offline record drafting (allowing reps to create, edit, and queue updates offline), enforces client-side encrypted storage on mobile hardware, and governs whether device address books can be synchronized with Salesforce Contacts. Tracking MobileSettings in version control ensures parity across development sandboxes, staging environments, and production.

Directory and File Conventions#

Like other org-level settings, MobileSettings is grouped under the parent Settings metadata type in Salesforce DX project source format.

Key Metadata Fields#

The MobileSettings XML schema defines parameters governing caching, offline data drafting, and client-side encryption:

Declarative XML and Package Manifest Examples#

The following example shows an enterprise Mobile.settings-meta.xml file configured for offline resilience and local data encryption:

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

Package Manifest (package.xml)#

Include Mobile under the Settings type in package.xml:

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy MobileSettings using the Salesforce CLI:

# Retrieve Mobile settings from target org
sf project retrieve start --metadata Settings:Mobile

# Deploy Mobile settings to target org
sf project deploy start --metadata Settings:Mobile

# Verify mobile settings via Tooling API
sf data query --use-tooling-api --query "SELECT Id, Metadata FROM MobileSettings"

Architect Best Practices and Gotchas#

• Encrypted Local Storage: Always enable enableS1EncryptedStoragePref2 in production orgs handling sensitive customer or financial data to ensure that local cached records are protected against device-theft forensic extraction.
• Offline Layout Dependencies: Enabling offline drafts allows records to be edited offline, but complex custom Lightning Web Components (LWCs) or Flows on record pages must be specifically architected using the Briefcase Builder and LWC Offline runtime to work without connectivity.
• Scratch Org Definitions: To test offline mobile flows in scratch orgs, declare mobileSettings in project-scratch-def.json:

  "settings": {
    "mobileSettings": {
      "enableOfflineDraftsEnabled": true,
      "enableS1EncryptedStoragePref2": true
    }
  }

Frequently asked questions

What does MobileSettings govern in Salesforce?

It governs org-wide settings for the Salesforce mobile app, including offline record creation drafts, local encrypted storage, and contact importing preferences.

Where is MobileSettings stored in SFDX format?

It is stored in force-app/main/default/settings/Mobile.settings-meta.xml in the source directory.

How is MobileSettings included in package.xml?

It is declared as a member of the Settings metadata type with member name Mobile in package.xml.

What does enableOfflineDraftsEnabled control?

It controls whether field workers can create and edit CRM records while offline, queuing them for automatic background sync upon reconnection.