With so many different flavors of streaming events, how do you choose the right one for your use case? In this post, we’ll talk about the use cases for each type of event and compare features across the different streaming events. Some events are used to generate notifications corresponding to Salesforce record changes, and other events are used to generate custom notifications.

What are streaming events and why use them?

Events are notification messages that are sent from one system (the publisher) to another (the subscriber). Using the publisher and subscriber model and push technology, notifications are sent to the subscriber in real time, ensuring freshness of data.

Push technology is the opposite of pull technology. With pull technology, clients request data from the server periodically. When systems are connected through pull technology, clients poll the server frequently. The received data might not always be the latest because it depends on the pull frequency. In addition, clients might make unnecessary calls and can cause server slowdown.

Streaming events connect disparate systems efficiently with Salesforce and deliver real-time data. By using an event-driven software architecture, you streamline the communication between enterprise systems. Clients can subscribe to an event channel to receive notifications.

What data is sent in streaming events?

Streaming events include Salesforce record changes or custom data that you specify. PushTopic events are published when a Salesforce record changes as a result of create, update, delete, or undelete operations. Alternatively, you can publish arbitrary data and subscribe to the stream of data using platform events or generic events.

Subscribe to Salesforce record changes

The Lightning Platform publishes real-time notifications when record changes occur through PushTopic events. Imagine each notification of a record data change to be like radar detection of a nearby object. Apps can subscribe to receive such notifications and take appropriate action, such as replicating Salesforce record data from Salesforce to an external system.

What is a PushTopic event?

A PushTopic event is a notification that Salesforce sends when a change to a Salesforce record occurs as part of a create, update, delete, or undelete operation. The notification is based on an SOQL query that you define. Changes are evaluated for fields specified in the query SELECT and WHERE clause. Notifications include the fields from the SELECT clause. The query’s maximum length is 1300 characters. PushTopic events support all custom objects and a subset of standard objects.

For example, this query causes notifications to be sent for account record changes. Each notification includes the account’s ID, Name, and Phone fields.

SELECT Id, Name, Phone FROM Account

Event payload example

This PushTopic event JSON message is sent when an account is created. The fields included in the event message are the fields specified in the query’s SELECT clause. Notice that Phone is null because no phone number was populated for the new account.

Example: Refreshing the UI of a custom app from Salesforce record changes

Robert is a software developer at Get Cloudy Consulting, a high-tech consulting firm specializing in CRM implementations. Robert is developing a custom app for a client, which is used by the client’s service reps and displays a feed of case records from Salesforce.

The app has the following requirements:

• The feed stays up-to-date and displays the latest changes from Salesforce without the need for reps to click the Refresh button.
• If a new case is assigned to a rep, the case is added to the feed.
• If the status or subject of a case is changed, the data is refreshed in the case feed.
• If a case is escalated, a red exclamation point is added to the case in the feed.

Robert decides that PushTopic streaming fulfills the client’s requirements. With PushTopic streaming, the app can subscribe to a PushTopic that he defines with a custom query. The PushTopic query selects all cases the rep has access to. Robert writes and executes this Apex code to create the PushTopic:

When a new case is created, the app receives a notification about this case. Thanks to sharing rules support, the app receives only notifications for the cases that the rep is allowed to view. Using subscription filtering, the app can show only the cases that are assigned to the logged-in rep by filtering on the OwnerId field in the channel, as follows.

Also, when a case subject or status is updated, the app updates those field values in the feed. If a case’s priority is High, the app adds a red exclamation point next to the case feed entry on the page.

Publish and subscribe to custom notifications

Business apps can communicate with each other using an event-based architecture by publishing and subscribing to event streams. With platform events and generic events, apps can publish custom messages and subscribers can listen to the notifications and take appropriate action. For example, a Salesforce order app can publish an event when an opportunity closes. An external order fulfillment app can listen to the order event and start the order shipping process.

What is a platform event?

A platform event message is a custom notification that you can publish and subscribe to. You define the schema of a platform event by creating a platform event and adding fields. Platform event notifications can include any type of data, such as business data or order information.

Event payload example

This platform event JSON message is sent when you publish an event of type Low_Ink__e. The Low_Ink__e event must be defined in the org first. The low ink event is published every time the ink level of a printer falls below a threshold.

You define the Low_Ink__e in Setup and add fields representing the schema of the data that is included in the event, as shown in this image.

Example: Order placement app

Get Cloudy Consulting has a new project: an order placement app. Robert, the software developer, is getting help from Awhina, the resident Salesforce admin expert, and they’re excited to tackle this project. A client wants a custom app that lets its users place orders for parts. When a user places an order through the Salesforce app, the app notifies the external parts supplier service. When the supplier ships the parts order, the Salesforce app is notified, posts a message in Chatter, and updates a case.

The order placement app has the following requirements:

• The notification to the external service is in real-time (or near real-time within seconds of the order placement), as well as the notifications received back from the service.
• The order data sent in the notifications is based on a customizable schema.

Awhina and Robert pick platform events for the Salesforce order app. Because platform events are supported on and off the platform and support declarative tools, they are the ideal choice.

First, Awhina can define the platform event schema by creating a custom platform event for the order and adding fields. Awhina also builds the Salesforce app that publishes platform event notifications to an external service. Robert works with the external parts supplier to build a service which listens to the platform event channel using CometD.

Next, Awhina creates a Process Builder process that listens to the platform event notifications sent by the fulfillment service. When an event notification is received, the process posts a message on Chatter and updates a case.

What is a generic event?

A generic event is a custom notification that you can publish and subscribe to. The payload of a generic event is arbitrary data in JSON format. You can subscribe to generic events only with CometD, which is an open-source library that simulates push technology.

Event payload example

This generic event message is published with a literal text string as its payload field value.

Example: Broadcast a message to service reps

In the first example, Robert from Get Cloudy Consulting develops an app for service reps that displays a feed of each rep’s cases. Get Cloudy’s client adds one more requirement for this app: the app should display notification messages that the service rep manager sends from a console app in Salesforce. For example, the manager can send notifications to specific reps about important events, such as system maintenance announcements or warnings of a rep’s low number of resolved cases.

Because the notification is sent only to specific service reps, Robert chooses generic events. Robert updates the console app to publish generic notification messages via REST API to the reps’ user IDs. Next, Robert modifies the service app to subscribe to the generic event channel and adds a banner in the app’s UI for displaying the message content.

How to subscribe to events using EMP Connector

Now that you learned about the various streaming events, let’s see take a look at a handy tool that lets you subscribe to events and displays event messages. EMP Connector is an open-source Java library and command-line tool that enables you to subscribe to any type of streaming event (PushTopic, platform event, or generic). EMP Connector uses CometD.

Important: EMP Connector is a free, open-source, community-supported tool. Salesforce provides this tool as an example of how to subscribe to events using CometD. To contribute to the EMP Connector project with your own enhancements, submit pull requests to the repository on GitHub.

To build the EMP Connector project using Maven:

$ git clone https://github.com/forcedotcom/EMP-Connector.git

$ cd emp-connector

$ mvn clean package

The generated JAR file includes the connector and the LoginExample functionality. The shaded JAR contains all the dependencies for the connector, so you don’t have to download them separately. The JAR file has a -phat Maven classifier.

To run EMP Connector against your production org, type this command and supply your Salesforce login credentials and the channel to subscribe to. For example, if you want want to subscribe to a platform event with the name Low Ink, the channel would be /event/Low_Ink__e and this is the command.

$ java -jar target/emp-connector-0.0.1-SNAPSHOT-phat.jar <username> <password> /event/Low_Ink__e

The output looks as follows.
Subscribed: Subscription [/event/Low_Ink__e:-2]
Received:
{schema=3l1laWb62nM8omMU0waLdg, payload={Serial_Number__c=123, CreatedById=00550000001N45jAAC, CreatedDate=2018-06-12T18:18:42Z, Ink_Percentage__c=0.2, Printer_Model__c=MN-123}, event={replayId=1}}

Streaming event features

The following table compares the features offered by each streaming event.

Now that you know all about our three different types of events, we can’t wait to see what you create! We know that you might be thinking “Aren’t they missing an event type?” You would be correct, so keep your eye on the Salesforce Developer blog for another post soon about Change Data Capture Events.

Resources

PushTopic and Generic Events

• Trailhead Unit: Use Streaming API (part of the API Basics Trailhead module and covers PushTopic and generic events)
• Streaming API Developer Guide

Platform Events

• Trailhead Module: Platform Events Basics
• Trailhead Module: Build an Instant Notification App
• Platform Events Developer Guide

About the author

Katia Hage is a technical writer on the platform content experience team at Salesforce.