Define and Manage Platform Events

By using platform events, publishers can send custom event data through Apex, a process, a flow, Pub/Sub API, or other APIs. Subscribers can receive custom event messages from Salesforce or an external system using Apex, Pub/Sub API clients, processes, or flows. Based on the event message data, subscribers can process custom business logic, such as sending an email or logging a case. For example, a software system monitoring a printer can make an API call to publish an event when the ink is low. The custom printer event can contain custom fields for the printer model, serial number, and ink level. The event is processed in Salesforce by an Apex trigger that places an order for a new cartridge.

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. Multiple subscribers can listen to the same event and carry out different actions.

Define Your Platform Event

To define a platform event in Salesforce Classic or Lightning Experience:

1. From Setup, enter Platform Events in the Quick Find box, then select Platform Events.
2. On the Platform Events page, click New Platform Event.
3. Complete the standard fields, and optionally add a description.
4. For Publish Behavior, choose when the event message is published in a transaction.
   • Publish After Commit to have the event message published only after a transaction commits successfully. Select this option if subscribers rely on data that the publishing transaction commits. For example, a process publishes an event message and creates a task record. A second process that is subscribed to the event is fired and expects to find the task record. Another reason for choosing this behavior is when you don't want the event message to be published if the transaction fails.
   • Publish Immediately to have the event message published when the publish call executes. Select this option if you want the event message to be published regardless of whether the transaction succeeds. Also choose this option if the publisher and subscribers are independent, and subscribers don't rely on data committed by the publisher. For example, the immediate publishing behavior is suitable for an event used for logging purposes. With this option, a subscriber can receive the event message before data is committed by the publisher transaction.
5. Click Save.
6. To add a field, in the Custom Fields & Relationships related list, click New.
7. To set up the field properties, follow the custom field wizard.

Note

• If you change the publish behavior, expect up to a 5-minute delay for the change to take effect.
• In Lightning Experience, platform events aren’t shown in the Object Manager’s list of standard and custom objects and aren’t available in Schema Builder.

A platform event is a special 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.

Standard Fields

Platform events include standard fields. These fields appear on the New Platform Event page.

Custom Fields

In addition to the standard fields, you can add custom fields to your custom event. Platform event custom fields support only these field types.

• Checkbox
• Date
• Date/Time
• Number
• Text
• Text Area (Long)

The maximum number of fields that you can add to a platform event is the same as for a custom object. See Salesforce Features and Edition Allocations.

ReplayId System Field:

Each event message is assigned an opaque ID contained in the ReplayId field. The ReplayId field value, which is populated by the system when the event is delivered to subscribers, refers to the position of the event in the event stream. Replay ID values aren't guaranteed to be contiguous for consecutive events. A subscriber can store a replay ID value and use it on resubscription to retrieve events that are within the retention window. For example, a subscriber can retrieve missed events after a connection failure. Subscribers must not compute new replay IDs based on a stored replay ID to refer to other events in the stream.

EventUuid System Field

A universally unique identifier (UUID) that identifies a platform event message. In Pub/Sub API clients, the event id field contains the event UUID value and isn't versioned. In other subscriber clients, the EventUuid field is available in API version 52.0 and later. The API version corresponds to the version that an Apex trigger is saved with, or the version specified in a CometD subscriber endpoint.

API Name Suffix for Custom Platform Events

When you create a platform event, the system appends the __e suffix to create the API name of the event. For example, if you create an event with the object name Low Ink, the API name is Low_Ink__e. The API name is used whenever you refer to the event programmatically, for example, in Apex. API names of standard platform events, such as AssetTokenEvent, don’t include a suffix.

Event Subscribers

The Subscriptions related list shows all triggers, processes, and platform event–triggered flows that are subscribed to a platform event. Pub/Sub API subscribers, CometD subscribers, such as your own CometD client or the empApi Lightning component, aren't listed in this page.

The list shows the replay ID of the event that the system last processed (Last Processed Id field) and the event last published (Last Published Id field). Knowing which replay ID was last processed is useful when there’s a gap in the events published and processed. For example, if a trigger contains complex logic that causes a delay in processing large batches of incoming events.

Note For high-volume platform events, the Last Published Id value isn't available and is always shown as Not Available.

Also, the Subscriptions list shows the state of each subscriber, which can be one of the following.

• Running—The subscriber is actively listening to events. If you modify the subscriber, the subscription continues to process events.
• Error— The subscriber was disconnected and stopped receiving published events. A trigger reaches this state when it exceeds the number of maximum retries with the EventBus.RetryableException. Trigger assertion failures and unhandled exceptions don’t cause the error state. We recommend limiting the retries to fewer than nine times to avoid reaching this state. When you fix and save the trigger, or for a managed package trigger, if you redeploy the package, the trigger resumes automatically from the tip, starting from new events. Also, you can resume a trigger subscription in the subscription detail page that you access from the platform event page.
• Suspended—The subscriber is disconnected and can’t receive events because a Salesforce admin suspended it or due to an internal error. You can resume a trigger subscription in the subscription detail page that you access from the platform event page. To resume a process, deactivate it and then reactivate it. If you modify the subscriber, the subscription resumes automatically from the tip, starting from new events.

Note Only one “Process” subscriber appears in the Subscriptions related list for all paused flow interviews that are subscribed to the platform event. Processes and platform event–triggered flows are listed individually.

Also, information about event subscribers is exposed in the EventBusSubscriber object. You can query this object to obtain details about subscribers.

Suspend or Resume an Apex Trigger Subscription:

Resume a suspended trigger subscription where it left off, starting from the earliest available event message that is stored in the event bus. If you want to bypass event messages that are causing errors or are no longer needed, you can resume a subscription from the tip, starting from new event messages.

To manage a trigger subscription:

1. In the Subscriptions related list, click Manage next to the Apex trigger.
2. In the subscription detail page, choose the appropriate action.
   • To suspend a running subscription, click Suspend.
   • To resume a suspended subscription, starting from the earliest event message that is available in the event bus, click Resume.
   • To resume a suspended subscription, starting from new event messages, click Resume from Tip.

You can’t manage subscriptions for flows and processes through the Subscriptions related list.

Note

• After you modify a subscriber, the subscription resumes automatically. For more information, see the Event Subscribers section.
• If you click Resume for a trigger that is in the error state, the trigger skips the events that were retried with EventBus.RetryableException. The subscription starts with the unprocessed events sent after the error state and that are within the retention window.

Platform Event Considerations

• Field-Level Security—All platform event fields are read only by default, and you can’t restrict access to a particular field. Field-level security permissions don’t apply and the event message contains all fields.
• Enforcement of Field Attributes—Platform event records are validated to ensure that the attributes of their custom fields are enforced. Field attributes include the Required and Default attributes, the precision of number fields, and the maximum length of text fields.
• Permanent Deletion of Event Definitions—When you delete an event definition, it’s permanently removed and can’t be restored. Before you delete the event definition, delete the associated triggers. Published events that use the definition are also deleted.
• Renaming Event Objects—Before you rename an event, delete the associated triggers. If the event name is modified after clients have subscribed to this event, the subscribed clients must resubscribe to the updated topic. To resubscribe to the new event, add your trigger for the renamed event object.
• No Associated Tab—Platform events don’t have an associated tab because you can’t view event records in the Salesforce user interface.
• No SOQL Support—You can’t query event messages using SOQL.
• No Record Page Support in Lightning App Builder—When creating a record page in Lightning App Builder, platform events that you defined show up in the list of objects for the page. However, you can’t create a Lightning record page for platform events because event records aren’t available in the user interface.
• Platform Events in Package Uninstall—When uninstalling a package with the option Save a copy of this package's data for 48 hours after uninstall enabled, platform events aren’t exported.
• Event Volume in Package Installations and Upgrades—Installing a managed or unmanaged package that contains a standard-volume platform event causes the event type to be saved as high volume in the subscriber org. Upgrading a managed package doesn't change t he event volume in the subscriber org.
• No Support in Professional and Group Editions—Platform events aren’t supported in Professional and Group Edition orgs. Installation of a package that contains platform event objects fails in those orgs.