RealTimeEventSettings in SFDX

Architectural Overview#

In regulated enterprise environments, real-time threat detection and forensic audit trails are mandatory. Salesforce Shield Event Monitoring provides Real-Time Event Monitoring (RTEM) to detect credential compromises, unauthorized bulk data exfiltration, report exports, and suspicious API activity as it happens.

The RealTimeEventSettings metadata type manages real-time event streaming and storage policies across the tenant. It governs whether event streams—such as ApiEventStream, LoginEventStream, ReportEventStream, and ListViewEventStream—publish events to the Pub/Sub API for external Security Information and Event Management (SIEM) ingestion, and whether events are persisted to BigObjects for long-term forensic querying.

Managing real-time event configurations as code ensures security monitoring policies remain uniform and verifiable across all corporate Salesforce environments.

Directory and File Conventions#

In SFDX source projects, RealTimeEventSettings is organized as a singleton settings file:

Key Metadata Fields#

The XML schema of RealTimeEventSettings controls streaming and storage per event stream:

Declarative XML and Package Manifest Examples#

Below is an enterprise RealTimeEvent.settings-meta.xml configuration streaming and storing key security events:

<?xml version="1.0" encoding="UTF-8"?>
<RealTimeEventSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <realTimeEvents>
        <entityName>ApiEventStream</entityName>
        <isEnrichmentEnabled>true</isEnrichmentEnabled>
        <isStorageEnabled>true</isStorageEnabled>
        <isStreamingEnabled>true</isStreamingEnabled>
    </realTimeEvents>
    <realTimeEvents>
        <entityName>LoginEventStream</entityName>
        <isEnrichmentEnabled>true</isEnrichmentEnabled>
        <isStorageEnabled>true</isStorageEnabled>
        <isStreamingEnabled>true</isStreamingEnabled>
    </realTimeEvents>
    <realTimeEvents>
        <entityName>ReportEventStream</entityName>
        <isEnrichmentEnabled>true</isEnrichmentEnabled>
        <isStorageEnabled>true</isStorageEnabled>
        <isStreamingEnabled>true</isStreamingEnabled>
    </realTimeEvents>
</RealTimeEventSettings>

Scratch Org Definition Configuration#

{
  "orgName": "Shield Security Scratch Org",
  "edition": "Enterprise",
  "features": ["ShieldEventMonitoring"],
  "settings": {
    "realTimeEventSettings": {
      "realTimeEvents": [
        {
          "entityName": "LoginEventStream",
          "isStreamingEnabled": true,
          "isStorageEnabled": true
        }
      ]
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage RealTimeEventSettings via the Salesforce CLI:

# Retrieve RealTimeEvent settings from the org
sf project retrieve start --metadata Settings:RealTimeEvent

# Deploy RealTimeEvent settings to target environment
sf project deploy start --metadata Settings:RealTimeEvent

# Validate deployment into sandbox
sf project deploy validate --metadata Settings:RealTimeEvent

Architect Best Practices and Gotchas#

• Feature License Requirements: Deploying RealTimeEventSettings into an environment lacking Salesforce Shield Event Monitoring feature licenses will fail with Feature not supported.
• Pub/Sub API Streaming Subscription: When isStreamingEnabled is true, use Salesforce Pub/Sub API (gRPC) rather than legacy CometD clients to ingest high-velocity event streams into enterprise SIEMs with reliable replay capabilities.
• Transaction Security Integration: Real-Time events feed directly into Transaction Security Policies. When configuring policies to block report exports or require MFA, ensure emergency administrator bypass exceptions are implemented to prevent administrative lockouts.

Frequently asked questions

What is the primary architectural purpose of RealTimeEventSettings?

It configures streaming and storage policies for Salesforce Shield Real-Time Event Monitoring streams like ApiEventStream and LoginEventStream.

Where is RealTimeEventSettings stored in an SFDX source repository?

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

What is the difference between isStreamingEnabled and isStorageEnabled?

isStreamingEnabled broadcasts events to the Pub/Sub API in real time, while isStorageEnabled persists events to a BigObject for six months.

Can RealTimeEventSettings trigger transaction security policies?

Yes, Real-Time events feed directly into Transaction Security Policies to block malicious exports or enforce step-up MFA.