PlatformEventSettings in SFDX

Architectural Overview#

The PlatformEventSettings metadata type represents the foundational environment-level configuration for the Salesforce event bus. In distributed enterprise systems, platform events decouple publishers (e.g., core CRM workflows, ApexClass triggers) from subscribers (e.g., microservices, Kafka pipelines, external ERPs, and automated flows).

PlatformEventSettings controls the availability of the event publishing pipeline, retention parameters, and cross-system streaming connectivity. In scratch org automation and deployment pipelines, deploying PlatformEvent.settings-meta.xml guarantees that integration test suites have an active event bus initialized with the correct throughput limits.

Directory and File Conventions#

In SFDX source format, PlatformEventSettings is stored in the settings/ directory and referenced using the Settings type with member PlatformEvent.

Key Metadata Fields#

The XML schema of PlatformEventSettings exposes settings governing the event infrastructure:

Declarative XML and Package Manifest Examples#

Below is a declarative XML configuration for an active event bus:

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

Scratch Org Definition Configuration#

When testing event streaming pipelines in scratch orgs:

{
  "orgName": "Event Streaming Dev Org",
  "edition": "Enterprise",
  "settings": {
    "platformEventSettings": {
      "enablePlatformEvents": true,
      "enableEventPublishing": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage PlatformEventSettings via the Salesforce CLI:

# Retrieve PlatformEventSettings from target org
sf project retrieve start --metadata Settings:PlatformEvent

# Deploy PlatformEventSettings to remote environment
sf project deploy start --metadata Settings:PlatformEvent

# Validate settings deployment
sf project deploy validate --metadata Settings:PlatformEvent

Architect Best Practices and Gotchas#

• Emergency Circuit Breaker: Setting enableEventPublishing to false serves as an emergency architectural circuit breaker during runaway trigger loops or external API outages, immediately stopping new event publication without altering custom code.
• Publish Behavior Matching: Align platform event definitions (CustomObject with __e) with business semantics: use Publish After Commit for transactional data where database rollbacks must suppress events, and Publish Immediately for audit logging or uncommitted status notifications.
• Allocations and Governor Limits: While high-volume platform events support substantial daily throughput, each publishing call via EventBus.publish() consumes standard DML call limits per Apex transaction.

Frequently asked questions

What does PlatformEventSettings control in Salesforce?

PlatformEventSettings governs global streaming event bus capabilities, event publishing rules, and event retention parameters.

Where is PlatformEventSettings located in an SFDX project?

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

How long are platform events retained on the event bus?

High-volume platform events are retained for 72 hours by default, enabling subscribers to replay missed messages after network outages.

Can platform event settings be declared in scratch org configs?

Yes. Adding platformEventSettings to project-scratch-def.json ensures test orgs instantiate identical event bus limits as production.