ApexSettings Metadata Type in SFDX

Architectural Overview#

The ApexSettings metadata type controls critical org-wide switches for the Apex runtime, unit test execution engine, inbound email handlers, and historical data migration capabilities. For a Senior Salesforce Architect, version-controlling Apex.settings-meta.xml is essential for deterministic CI/CD pipelines and data migration cutovers.

For example, when migrating legacy records into Salesforce and populating CreatedDate, CreatedById, or LastModifiedDate, an architect must enable enableAuditFieldsInactiveOwner in ApexSettings before granting the corresponding system permissions inside a PermissionSet. Similarly, controlling enableDisableParallelApexTesting prevents or exposes UNABLE_TO_LOCK_ROW contention during automated test runs.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is an architect-recommended Apex.settings-meta.xml configuration that enables Approval.lock()/unlock(), protects auto-number sequences from unit test gaps, enables audit field permissions, and keeps parallel testing active (enableDisableParallelApexTesting set to false).

<?xml version="1.0" encoding="UTF-8"?>
<ApexSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableAggregateCodeCoverageOnly>false</enableAggregateCodeCoverageOnly>
    <enableApexAccessRightsPref>true</enableApexAccessRightsPref>
    <enableApexApprovalLockUnlock>true</enableApexApprovalLockUnlock>
    <enableAuditFieldsInactiveOwner>true</enableAuditFieldsInactiveOwner>
    <enableCompileOnDeploy>true</enableCompileOnDeploy>
    <enableDisableParallelApexTesting>false</enableDisableParallelApexTesting>
    <enableGaplessTestAutoNum>true</enableGaplessTestAutoNum>
</ApexSettings>

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

SFDX CLI Retrieval and Scratch Org Configuration#

Retrieve or deploy ApexSettings directly with the Salesforce CLI:

# Retrieve ApexSettings from your org
sf project retrieve start --metadata Settings:Apex --target-org my-org

# Deploy ApexSettings to target org
sf project deploy start --metadata Settings:Apex --target-org my-org

You can also inject ApexSettings directly into config/project-scratch-def.json so every new scratch org inherits these preferences at creation time:

{
  "orgName": "Enterprise Architecture Scratch Org",
  "edition": "Developer",
  "settings": {
    "apexSettings": {
      "enableApexApprovalLockUnlock": true,
      "enableAuditFieldsInactiveOwner": true,
      "enableDisableParallelApexTesting": false,
      "enableGaplessTestAutoNum": true
    }
  }
}

Senior Architect Best Practices and Gotchas#

1. Always Enable enableGaplessTestAutoNum: Without this setting, every time a developer or CI job runs Apex unit tests that insert records with Auto-Number fields (like CaseNumber or Invoice_Number__c), the sequence counter increments permanently even though the test transaction rolls back. Enabling enableGaplessTestAutoNum isolates test auto-numbers from production sequences.
2. Dependency Order with PermissionSet: If a PermissionSet in your repository includes <userPermissions><name>CreateAuditFields</name><enabled>true</enabled></userPermissions>, Apex.settings-meta.xml with <enableAuditFieldsInactiveOwner>true</enableAuditFieldsInactiveOwner> must be enabled in the org; otherwise, the permission set deployment fails with Unknown user permission: CreateAuditFields.
3. Compile on Deploy Trade-offs: Setting enableCompileOnDeploy to true is recommended for production cutovers so business users do not experience a freeze the first time a trigger runs after deployment, but keep it false in scratch orgs and CI validation sandboxes to keep deployment times fast.

Frequently asked questions

How do I disable parallel Apex test execution via Metadata API?

Set enableDisableParallelApexTesting to true inside force-app/main/default/settings/Apex.settings-meta.xml and deploy the Settings:Apex component.

Why is enableDisableParallelApexTesting named with a double negative?

The checkbox in Setup is labeled Disable Parallel Apex Testing, so setting enableDisableParallelApexTesting to true turns on that checkbox and forces serial test execution.

What setting allows Apex and API integrations to populate CreatedDate and CreatedById?

Setting enableAuditFieldsInactiveOwner to true in ApexSettings enables the Set Audit Fields upon Record Creation and Update Records with Inactive Owners permissions in the org.

Where is ApexSettings stored in a Salesforce DX project?

It is stored at force-app/main/default/settings/Apex.settings-meta.xml and referenced in package.xml under the Settings type with member name Apex.