Introducing Generic Streaming

Generic streaming uses Streaming API to send notifications of general events that are not tied to Salesforce data changes.

Use generic streaming when you want to send and receive notifications based on custom events that you specify. You can use generic streaming for any situation where you need to send custom notifications, such as:

Broadcasting notifications to specific teams or to your entire organization
Sending notifications for events that are external to Salesforce

To use generic streaming, you need:

A StreamingChannel that defines the channel, with a name that is case-sensitive
One or more clients subscribed to the channel
The Streaming Channel Push REST API resource that lets you monitor and invoke push events on the channel

Replay Generic Streaming Events with Durable Generic Streaming

A client can receive generic streaming events after it subscribes to a channel and as long as the Salesforce session is active. Events sent before a client subscribes to a channel or after a subscribed client disconnects from the Salesforce session are missed. However, starting with API version 36.0, a client can fetch the missed events within the 24-hour retention window by using Durable Generic Streaming.

The subscriber can choose which events to receive, such as all events within the retention window or starting after a particular event. The default is to receive only the new events sent after subscribing. Streaming API uses an event framework that decouples event producers from event consumers. Therefore, a subscriber can retrieve events at any time and isn’t restricted to listen to events at the time they’re sent. Events outside the 24-hour retention period are discarded.

API Version

Replaying events is supported with API version 36.0 and later.

Event Numbering

Each broadcasted event is assigned a numeric ID. IDs are incremented sequentially, but they’re not guaranteed to be contiguous for consecutive events. For example, the event following the event with ID 999 can have an ID of 1,025. However, each ID is guaranteed to be higher than the ID of the previous event. The ID is unique for the org and the channel. The IDs of deleted events aren’t reused.

The ID is added in the replayId field of the notification message. For example, this JSON message shows the replayId field in the event object.

1{
2 "clientId":"a1ps4wpe52qytvcvbsko09tapc",
3 "data":{
4    "event":{
5            "createdDate":"2015-11-13T19:05:28.334Z",
6            "replayId":55
7        },
8    "payload":"This is a message."
9    },
10 "channel":"/u/TestStreaming"
11}

In API version 36.0, the time format of the createdDate field value has also changed to make it consistent with the time format used in the Salesforce app. The time portion now ends with the Z suffix instead of +0000. Both suffixes denote a UTC time zone.

Replaying Events

The following diagram shows a high-level overview of a stream of events and how event consumers can read events by using various replay options.

Diagram showing a stream of events with replay options

Table 1. Replay Options
Replay Option	Description
Replay ID	Subscriber receives all events after the event specified by its replayId value.
-1	Subscriber receives new events that are broadcast after the client subscribes.
-2	Subscriber receives all events, including past events that are within the 24-hour retention window and new events sent after subscription.

To replay events, use the following endpoint.

1https://Salesforce_Instance/cometd/replay/36.0/

The replay mechanism is implemented in a Salesforce-provided CometD extension called cometdReplayExtension. Register this extension and then call the setReplay() function. The following example registers the extension in JavaScript.

1// Register streaming extension
2var replayExtension = new cometdReplayExtension();
3replayExtension.setChannel(<Streaming Channel to Subscribe to>);
4replayExtension.setReplay(<Event Replay Option>);
5cometd.registerExtension('myReplayExtensionName', replayExtension);

The argument passed to setReplay() is one of the replay options listed in Replay Options.
The first argument passed to registerExtension() is the name of the replay extension in your code. In the example, it is set to myExtensionName, but it can be any string. You use this name to unregister the extension later on.
If the setReplay() function isn’t called, or the CometD extension isn’t registered, only new events are sent to the subscriber (same as the -1 option).

Note

After calling the setReplay() function on the extension, the events that the subscriber receives depend on the replay value parameter passed to setReplay().

Code Sample

For a code sample on how to replay generic streaming events, see Example: Replay Generic Streaming Events Using a Visualforce Page.