Platform Events Developer Guide

Delivering Custom Notifications with Platform Events
Event-Driven Software Architecture
Enterprise Messaging Platform Events
Defining Your Platform Event
Publishing Platform Events
Subscribing to Platform Events
Test Your Platform Event in Apex
Considerations
End-to-End Example Using a Process and a Flow
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Enterprise Messaging Platform Events

The Salesforce enterprise messaging platform offers the benefits of event-driven software architectures. Platform events are the event messages (or notifications) that your apps send and receive to take further action. Platform events simplify the process of communicating changes and responding to them without writing complex logic. Publishers and subscribers communicate with each other through events. One or more subscribers can listen to the same event and carry out actions.

For example, a software system can send events containing information about printer ink cartridges. Subscribers can subscribe to the events to monitor printer ink levels and place orders to replace cartridges with low ink levels.

Platform events are defined in Salesforce in the same way that you define custom objects. Create a platform event definition by giving it a name and adding custom fields. The custom fields define the data that is sent in the event messages. Platform events support a subset of field types in Salesforce. See Platform Event Fields. This table lists a sample definition of custom fields for a printer ink event.

Field Name Field API Name Field Type
Printer Model Printer_Model__c Text
Serial Number Serial_Number__c Text
Ink Percentage Ink_Percentage__c Number

You can publish and consume platform events by using Apex or an API. Platform events integrate with the Salesforce platform through Apex triggers. Triggers are the event consumers on the Salesforce platform that listen to event messages. When an external app through the API or a native Salesforce app through Apex publishes the event message, a trigger on that event is fired. Triggers run the actions in response to the event notifications. Using the printer ink example, a software system monitoring a printer makes an API call to publish an event when the ink is low. The printer event message contains the printer model, serial number, and ink level. After the printer sends the event message, an Apex trigger is fired in Salesforce. The trigger creates a Case record to place an order for a new cartridge.

External apps can listen to event messages by subscribing to a channel through CometD. Platform apps, such as Visualforce pages and Lightning components, can subscribe to event messages with CometD as well.

Platform Events and sObjects

A platform event is a special kind of Salesforce entity, similar in many ways to an sObject. An event message is an instance of a platform event, similar to how a record is an instance of a custom object. Unlike custom objects, you can’t update or delete event records. You also can’t view event records in the Salesforce user interface, and platform events don’t have page layouts. When you delete a platform event definition, it’s permanently deleted.

You can set read and create permissions for platform events. Grant permissions to users in profiles or in permission sets.

Platform Events and Transactions

Unlike custom objects, platform events aren’t processed within database transactions in the Lightning platform. As a result, published platform events can’t be rolled back. Note the following:

  • The allOrNoneHeader API header is ignored when publishing platform events through the API.
  • The Apex setSavepoint() and rollback() Database methods aren’t supported with platform events.

When publishing platform events, DML limits and other Apex governor limits apply.

Event Retention

Platform event messages are stored for 24 hours. You can retrieve past event messages when using CometD clients to subscribe to a channel.

High-Volume Platform Events (Pilot)

We provide High-Volume Platform Events to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can’t guarantee acceptance. High-Volume Platform Events isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for High-Volume Platform Events in this Trailblazer Community group.

Note

Use high-volume platform events to publish and process millions of events efficiently and to scale your event-based apps. Choose the platform event type that suits your business needs. For applications that receive several million events per day, use high-volume platform events through the pilot program. For applications that receive up to a million events per day, use standard-volume platform events.

Like for standard-volume platform events, you can define a high-volume platform event from the user interface or through Metadata API. Define a high-volume platform event by setting its event type to High Volume.

Publish and subscribe to high-volume platform events in the same way that you publish and subscribe to standard-volume platform events. You can use declarative tools, such as Process Builder and flow, or write code with Apex and CometD API apps.

Note the following characteristics of high-volume platform events.

Asynchronous Publishing
For efficient processing of high loads of incoming event messages, high-volume platform events are published asynchronously. After the publishing call returns with a successful result, the publish request is queued in Salesforce. The event message might not be published immediately. In contrast, standard-volume events are published immediately and synchronously.
Separate Event Allocations
Some allocations for high-volume platform events, such as the number of event notifications published per hour, are higher than for platform events. See Platform Event Allocations.
Event Retention
High-volume platform event messages are stored for up to three days. You can retrieve past event messages when using CometD clients to subscribe to a channel.