Overview

Streaming notifications in Force.com are best understood in terms of publishers and subscribers. Force.com can be configured to publish notifications when something interesting happens with a database object. This publishing configuration is expressed through a PushTopic. The PushTopic defines the database object to monitor, a public name that subscribers can reference called a Channel, and guidance on what conditions in the database object must be satisfied to create a notification. The subscriber is a program inside or outside of Force.com that uses the Bayeux protocol (CometD implementation) to register interest in and receive the streaming notifications.

PushTopics are ordinary Force.com database records, but contain four components that are critical to properly configuring your streaming notifications, described in the following list:

1. Channel name—This is the name that client applications will use to subscribe to the streaming notifications on this PushTopic. It must be 25 characters or fewer and be unique in your organization.

2. SOQL query—The SOQL query defines the database object and fields that you are monitoring for changes, plus optionally the criteria used to determine whether a change is worthy of a notification. To receive notifications, the subscriber must have at least read access to the object, field-level security to the fields in the WHERE clause, and visibility to the records causing the notifications via sharing rules.

3. NotifyForOperations—By default, notifications are sent on the Channel when matching records are created or updated (All). Use this field to limit notifications to only creation (Create) or only modification (Update) of records.

4. NotifyForFields—This setting instructs the Channel on what fields in the SOQL query are considered changes and trigger a notification. Any filters in a WHERE clause are always evaluated first. By default, it is set to Referenced, which means all fields in the query are factored into the decision. Other valid values are All (all fields in the object, even those not in SELECT or WHERE), Select (fields in a SELECT clause only), and Where (fields in a WHERE clause only).

As soon as a PushTopic is created, it is instantly available to subscribers. Likewise, when it is modified, the new definition takes effect immediately. You can delete a PushTopic record to stop its notifications, or set IsActive to false to disable it temporarily.

Each Force.com organization has a limit of 20 PushTopics. There are also per-edition limits on subscribers per topic and notifications per day. There are also a number of limitations on the SOQL query used in PushTopics, described next:

Subset of objects—All custom objects are supported, but only a handful of standard objects: Account, Campaign, Case, Contact, Lead, Opportunity, and Task.

Subset of query features—Aggregate queries, semi-join and anti-joins, count, limit, relationship fields, order by, group by, and formula fields are not supported.

Required fields—The query must include the Id field.

Maximum length—The query cannot exceed 1,300 characters.