Use Pub/Sub API
Learning Objectives
After completing this unit, you’ll be able to:
- Describe the characteristics of Pub/Sub API.
- Describe the various event products supported by Pub/Sub API.
- Explain the use of the event bus and how to specify replay options.
Streaming Events
To conclude our survey of Salesforce’s data APIs, let’s look at an API that serves an entirely different use case. Pub/Sub API enables you to subscribe to real-time event streams and integrate external systems with real-time events. Event streams are based on custom payloads through platform events or changes in Salesforce records through Change Data Capture. Within Salesforce, you can publish and subscribe to events with Apex triggers, Process Builder, and Flow Builder.
As we mentioned in unit 1, Pub/Sub API is built for high scale, bi-directional event integration with Salesforce. Use Pub/Sub API to efficiently publish and subscribe to binary event messages in the Apache Avro format. Pub/Sub API is based on gRPC and HTTP/2 and uses a pull-based model so you can control the subscription flow. The Pub/Sub API service is defined in a proto file. With Pub/Sub API, you can use one of the 11 programming languages that gRPC supports.
Tracking data changes in Salesforce is especially useful when you have business data stored in a system external to Salesforce. You can use Pub/Sub API to keep your external source in sync with your Salesforce data with change data capture events. Also, the API lets you process business logic in an external system in response to data changes in Salesforce. For example, you can use Pub/Sub API to notify a fulfillment center whenever an opportunity is updated.
In addition to data changes, you can use Pub/Sub API to send custom notifications with platform events. For example, an app can generate platform event notifications for orders that an order fulfillment service processes. Or an app can listen to platform events that Salesforce publishes to monitor user activity in Salesforce.
Pub/Sub API and Event Products
These are the events you can publish and subscribe to.
- Change Data Capture—With Change Data Capture, you get changes of records of all supported changed fields. Record operations tracked include record creation, update, delete, and undelete. Each event message contains header fields with information about the change.
- Platform Events—With custom platform events, you can publish and subscribe to custom notifications. You can define the schema of the event data by creating platform event objects and fields. Also, you can subscribe to standard platform events that are defined and published by Salesforce, such as real-time Event Monitoring events, to monitor user- and security-related activity in Salesforce and other things.
All the event products make use of the event bus, which is a service that enables the storage and retrieval of event messages.
Platform Events and Change Data Capture, offer flexibility, scalability, and enhanced security.
- You can subscribe to platform events and change data capture events with Apex triggers. In addition, platform events support subscription with flows and processes.
- They support encryption at rest of event data.
- The versioned schema of a platform event or change data capture event enables subscribers to deterministically parse events. Each schema version corresponds to a unique schema ID, which is included in the event notification message.
- Change Data Capture includes header fields that contain information about the change.
Retrieve Past Notifications Using the Event Bus
Starting with API version 37.0, events are published to the event bus. Subscribers retrieve events from a channel on the event bus, including past events that are stored temporarily. The event bus decouples event publishers from event subscribers.
Salesforce stores high-volume platform events and change data capture events for 72 hours. Retrieving stored event messages from the event bus enables you to catch up on missed events when the client was disconnected.
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 are not 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.
In addition, there are other replay options, which are listed in this table. The replay options are specified in the ReplayPreset
enum.
ReplayPreset Option | Description | Usage |
---|---|---|
CUSTOM with Replay ID |
Subscriber receives all stored events after the event specified by its replayId value and new events. |
Catch up on missed events after a certain event message, for example, after a connection failure. To subscribe with a specific replay ID, save the replay ID of the event message after which you want to retrieve stored events. Then use this replay ID when you resubscribe. Store replay ID values as bytes because replay IDs are opaque. |
LATEST |
Subscriber receives new events that are broadcast after the client subscribes. |
We recommend that clients subscribe with the LATEST option to receive new event messages. If clients need to get earlier event messages, they can use any other replay option. |
EARLIEST |
Subscriber receives all events, including past events that are within the retention window and new events. |
Catch up on missed events and retrieve all stored events, for example, after a connection failure. Use this option sparingly. Subscribing with the EARLIEST option when a large number of event messages are stored can slow performance. |
This diagram shows how event consumers can read a stream of events by using various replay options.
Resources
Platform Events Developer Guide
- Defining Platform Events
- Publishing Platform Events
- Subscribing to Platform Events
- What’s the Difference Between the Salesforce Events?