[Salesforce / Streaming API / On Demand] Streaming API Notification Lightning Component

UPDATE: With Winter '15 you no longer can use a lightning context Session ID to make REST API calls, this component no longer works. Read Session Privilege Levels.

Few weeks ago I asked the community this simple question:

The Salesforce Community is awesome and suddenly I had cool answers.

I concentrated on the first one:

I didn't want to simply explain how Streaming APIs work and at the same time I wanted to do something fun and while I was walking with my dog I thought:

If you have any idea please send me awesome and challenging on demand articles topics!

For TL;DR buddies, here is the complete GitHub repository.

First of all here is the complete guide on Salesforce Streaming APIs.

As usual, this is a "quick and dirty" blog post, so don't expect me to explain how the magic works.

Streaming API is a cool set of APIs which allow a client to be notified from the server when a specific event occurs.

It works like push notifications and uses long polling, in the sense that the client polls for updates from the server but the server doesn't answer back till the next event (the connection remains idle), and when the client receives finally the response it usually makes another logn polling request, and so on.

This is what happens:

1. client connects to the server (handshake)
2. client subscribes to a specific server event (called channel)
3. client listens to that event using long polling
4. server sends event
5. client consumes the event
6. back to step 2

This technology is based on the Bayeux protocol and supports the dialect of the CometD 2.0 library (that implements the Bayeaux protocol).

Here is some characteristics of the flow:

• Maximum "client to server" post body size is 32,768 bytes (e.g. connect or subscribe methods)
• After an event is received, the client has to reconnect withing 40 seconds or the server closes the connection and a new handshake is necessary
• In case of network problems, the client should attempt an automatic reconnection and a new subscription
• Client can subscribe to the meta/handshake channel to receive informations about the connection

Remember that "Streaming API doesn’t guarantee durability and reliable delivery of notifications": the server does'nt keep any state so it doens't keep track of what's delivered.

Here is a simple guide of using Streaming API with Workbech.

Enable a PushTopic

The PushTopic SObject is the mean for creating a Streaming API channel.

It hosts the query that originates the events sent to the subscribers.

These are the PushTopics we are going to use in our project:

PushTopic pushTopic1 = new PushTopic();
pushTopic1.Name = 'Opportunity_Won';
pushTopic1.Query = 'SELECT Id, Amount, Name FROM Opportunity Where StageName=\'Closed Won\'';
pushTopic1.ApiVersion = 36.0;
pushTopic1.NotifyForOperationCreate = true;
pushTopic1.NotifyForOperationUpdate = true;
pushTopic1.NotifyForFields = 'Where';
insert pushTopic1;

pushTopic = new PushTopic2();
pushTopic2.Name = 'Lead_Converted';
pushTopic2.Query = 'SELECT Id, Name,Company FROM Lead Where IsConverted = true';
pushTopic2.ApiVersion = 36.0;
pushTopic2.NotifyForOperationCreate = true;
pushTopic2.NotifyForOperationUpdate = true;
pushTopic2.NotifyForFields = 'Where';
insert pushTopic2;

The drivers of a PushTopic are:

• Query: this is the query used to create the data pool
• Operations: when a record has to scanned by the engine, that is on create, update, delete, udelete
• Fields: the record is scanned when fields change if they are in the WHERE clause, SELECT clause, REFERENCE (where+select) or ALL (all fields changes trigger the PushTopic, if the where clause still apply)

In our examples we are subscribing to the create/update operations on the leads and opportunity when leads are converted and opportunities are closed and won.

Users will receive a notification if FLS (field level security) allow them to view the topic fields, if they have read access to the record and to the PushTopic, visibility on the record based on the sharing rules.

Limitations

The following objects can be used in the PushTopi query:

• All Custom Objects
• Account
• Campaign
• Case
• Contact
• Lead
• Opportunity
• Task (with few limitations)

And here you are a list of unsupported SOQL statements.

There are also a number of limits all exposed in this page.

The Lightning playroom

The GitHub repository provides the following components:

• svg: replicates the svg HTML5 element not currently supported in Lightning components (outputs icons and stuff)
• UINotification: used to display a alert/toast notification when a specific event occurs. You can choose the style (info, error, success, warning), type (Toast, Alert) and the timer in seconds for auto-hiding, and ofcourse a title and a content detail
• StreamingAPIEvent: event fired when a specific channel sends an event
• ShowNotificationEvent: event fired whan a Streaming API event is consumed and allow for displaying a notification
• StrApiListener: subscribes client to one or several topics (only one component is allowed per app); it fires a StreamingAPIEvent event.
• StrApiTopicTemplate: (global component) listens to the StreamingAPIEvent event, grabs its content, compile its templates for title and content and fires a ShowNotificationEvent to the unique notification center
• StrApiNotificationDock: (global component) hosts the StrApiListener component and handles ShowNotificationEvent events, dynamically creating UINotification component

The StrApiTestApp hosts the following components instances:

<aura:application>
    <!-- ... -->

    <c:StrApiNotificationDeck topics="Opportunity_Won,Lead_Converted"
        apiVersion="36" 
        notificationType="Alert" />
    
    <c:StrApiTopicTemplate topic="Lead_Converted"
                                 style="warning" 
                                 title="Created new lead called {{Name}}"
                                 content="Company: {{Company}}"/>
    <c:StrApiTopicTemplate topic="Opportunity_Won"
                                 style="success" 
                                 title="Won $ {{Amount}} !"
                                 content="Name is {{Name}}" />
</aura:application>

The StrApiNotificationDeck subscribes to the Opportunity_Won and Lead_Converted PushTopics using an Alert notification style.

For each channel defines a StrApiTopicTemplate template with a proper notification style, title and content.

Title and Amount attributes can be templates referring to the corresponding SObject's fields wrapped by the double moustaches ({{Field__c}}).

Run to https://xxx.lightning.force.com/c/StrApiTestApp.app:

Lightning App Builder

The StrApiNotificationDeck and StrApiTopicTemplate components are defined as global and implements the flexipage:availableForAllPageTypes interface so they are good to go with the Lightning App Builder.

Compoments are invisible so you are not expected to see anything on the builder: as far as I know there is not way to create a sort of "default" view for the builder.

And this is your Salesforce 1 brand new app:

Custom Streaming Channels

The Force.com platform allows for custom channels.

They can be access by:

• Creating a new StreamingChannel object
• Sending a notification to the channel using the Streaming Channel REST API

To create a new StreamingChannel go to All Tabs > Streaming Channel and create a new streaming channel:

The Name must include the "/u/" prefix. You can specify whichever path you like (e.g. /u/users/alerts, /u/sales/notifications).

The components we have creates supports this new kind of channel:

<c:StrApiNotificationDeck topics="Opportunity_Won,Lead_Converted,/u/CustomChannel"
        apiVersion="36" 
        notificationType="Alert" 
        hideAfter="5"/>
    
    <!-- . . . -->

    <!-- custom streaming channel -->
    
    <c:StrApiTopicTemplate topic="/u/CustomChannel"
                                 style="info" 
                                 title="Message received"
                                 content="{{$}}" />
    

The template component supports the {{$}} value that stands for "the whole data".

Indeed the StreamingChannel supports only strings.

To execute a REST push call follow the following instructions, or manually execute the following call:

Header:

"method":"POST",
    "uri":"https://[YOUR_DOMAIN].salesforce.com/services/data/v36.0/sobjects/StreamingChannel/[STREAMING_CHANNEL_ID]/push",
    "headers":[
        {
            "key":"Authorization",
            "value":"Bearer [YOUR_SESSION_ID]"
        },
        {
            "key":"Content-Type",
            "value":"application/json"
        }
    ]

Body:

{ 
      "pushEvents": [
          { 
              "payload": "Broadcast message!!!!",
              "userIds": [] 
          },{ 
              "payload": "This message is only for Enreeco!!!",
              "userIds": ["00524000000eaVt"] 
          } 
       ] 
    }

The messages are composed by:

• payload: the message to be sent (plain text)
• userIds: leave empty Array for broadcast message, of add one or more user Ids

May the Force.com be with you!