The Salesforce Streaming API (with example!)
by Bryan Leboff
What is it???
The Salesforce Streaming API is a simple way to push relevant data to your users in realtime, instead of having to refresh the screen to get new information.
This allows a user to get information without having to perform any action to retrieve it, essentially pushing new data to the screen.
Cool. How does it work?
The Streaming API uses a publisher subscriber (pub/sub) model to push data to the client. The first thing a developer must do is set up a PushTopic in Salesforce. This is basically a query that watches for changes in values of certain fields in a Salesforce Object. Then the client can subscribe to that PushTopic and receive updates whenever a change is made to the specified fields. This is done using a push protocol called the Bayeux protocol. The Salesforce implementation uses long polling connections to the server that will be able to notify the client on changes. This differs from traditional polling in that it keeps an incoming request open until an event is fired and then sends the response.
Here’s how this works. An http request is made to the server. Instead of responding immediately, the server keeps the request and waits for a specific event to fire, in our case a change in one of the fields of our PushTopic object. When the event is fired a response is made. Then the client makes another request to the server which it keeps open and waits. This ends up looking something like this:
Ok… but how would I use this?
Let’s say we’re Orange Party Cup Company and we have invented a revolutionary new party cup (one that is orange as opposed to red). We also sell and manufacture these cups. Our salespeople are on the phone day and night trying to get our plastic cups into the hands of party-goers everywhere, as quickly as possible.
We need to create a system that would notify our warehouse immediately every time a new order came in. Then they could package, and ship that order and mark it as completed in our Salesforce org.
Create our Order Object
So first we need to create our order object. This is where our salespeople will enter order information such as address and quantity. Not very complicated but necessary in order to create a PushTopic that watches for creation of this object. Mine looks like this:
Create our PushTopic
Next we must create our PushTopic. The easiest way to do this is to either use the workbench at developerforce.com or the developer console. I’m going to use the developer console. In the console head to Debug -> Execute Anonymous Apex Code. We are essentially creating a SOQL query with a few extra parameters that watch for changes in a specified object.
Note we have added a Name so that we can subscribe to this specific topic, and we are only want notifications on the ‘Create’ operation. If you were to choose ‘All’ it would notify every time one is created, or an update is made to any of the fields in your query.
Visualforce Page/Controller
Now that we have our PushTopic, let’s create our Visualforce Page that will display the newly created orders that have not yet been completed. In order to do this we need to add some javascript files. We are using the CometD implementation which you can find here
The easiest way to get the files you need is to unarchive the .war file located in
cometd-2.2.0 2/cometd-javascript/jquery/target/cometd-javascript-jquery-2.2.0.war
Then zip up the ‘org’ and ‘jquery’ folders, and call the new zip file streaming.zip. It should look like this:
Upload this new file as a static resource to your org. With the static resources in place we can create our VF page and controller. Mine look like this:
OrderStream Visualforce Page
OrderStreamControllerAs we can see the Visualforce page is pretty simple and standard with a few added javascript pieces. Tjhe javascript initializes CometD and then subscribes to /topic/OrderCreation which is our PushTopic. Now whenever an update comes across we call our action function reload(); which will reload the OrderTopics since we know there is now a new one. For reference the message we receive in our subscription is a JSON message that looks something like this:
This message contains field values that you requested so you can do direct javascript manipulation if you’d prefer.
That’s it! (can you believe it was that easy?) Now we can ship our revolutionary Orange Party Cups faster than ever! Check it out in action below. Leave any thoughts or questions in the comments.
Unable to display content. Adobe Flash is required.
.png)
