As I mentioned in my earlier post, SAP StreamWork saw some significant changes in the last quarterly release. Specifically, StreamWork has placed more focus on the events that take place inside the Activity workspaces. Although we will be doing some refinements after receiving feedback on the Activity homepage, we will continue to see focus on the events of work, as much as the work itself. The new version also saw the addition of a user profile status update feature, where users can share their status with colleagues in their organization, and the larger group of StreamWork users who choose to “follow” their updates. These enhancements all cumulated with the enhancement of the global “Updates” page, which now displays the updates from both the activities and people that you follow.
With this new focus on work events and activities, StreamWork has declared its support for the Activity Streams (http://activitystrea.ms (http://activitystrea.ms)) XML protocol. Our support for this protocol and the requisite APIs to take advantage of the StreamWork feed will be the focus of this post.
Feed API
StreamWork now has two REST web services: the Integration API (https://streamwork.com/api/Table_of_Contents.html) and the Feed API (https://streamwork.com/api/feeds/Table_of_Contents.html). The StreamWork Integration API requires clients to use 3 Legged OAuth to authorize API requests and is generally used to retrieve a user’s Activity Stream feed or the feed of an activity that the user belongs to.
The Feed API, which uses 2 Legged OAuth, is primarily used to post new feed events from third party client applications. These feeds are then aggregated with the feeds from other applications as well as the events coming from StreamWork itself. The real value is in allowing the user to see an aggregated feed from all of the applications they use in a single place, thus allowing them to use multiple applications for multiple tasks, but also allowing them to easily access one stream of work events from all their tools.
Retrieving the feed
To retrieve the feed of user or an activity you follow, you must use the standard 3 Legged OAuth authorization which requires you to get authorization from that user to make the call.
The Feed API end-points that use 3Legged OAuth are:
Get the users and activities that the current user follows
Get the users that follow the current user
Get the current user's follows feed
Get the feed for a specific activity
Add a user to a follows list
Add an activity to a follows list
Post a status update to a user's profile
Remove a user from a follows list
Remove an activity from a follows list
Since we already have a lot of documentation on how to use standard 3Legged OAuth calls for all of the other Integration API calls, I’m going to move on to the 2 Legged OAuth calls that StreamWork supports. With 2 Legged OAuth we are removing the end user from the story. To get access to the Feed API end-points that use 2Legged OAuth, developers must check the “Feed API” check box when registering their OAuth client applications with StreamWork. This alerts the StreamWork team to contact you and give you access to these end-points for specific Organizations inside of StreamWork. Organizations are a feature that is only available to StreamWork professional users, and gives the users extra activities, storage, security, and management based on an organizational unit. Once your feed application has been give access to a specific Organization, your application will be free to submit new “Topics” and events into those organizations.
Topics are event containers that feed applications can create and submit feeds into. They work as a security context which can be used to keep sensitive event updates private to specific groups of people. They work very similar to StreamWork Activities. Topics can represent almost anything that could generate events. For example Topics could represent a sales opportunity in a CRM, or it could represent a team room where private conversations can be had with colleagues. Currently feed applications can only create topics in organizations that they have been give access to. Here’s how it would work:
POST /v1/org_feed//topics</li><li>Feed app assign users to follow the Topic --> POST /v1//follows/</li><li>Feed app post events into the topic on behalf of users in the org --> POST /v1/user_feed/topics</li></ul><p>In the calls above you will notice that you will be required to provide both the Org id and the user id on whose behalf you will be creating topics and posting events. We currently provide two APIs for applications to get this information.</p><ul><li>Retrieve all the orgs that your application has access to --> GET /v1/org_feed/organization</li><li>Retrieve all the users that are in the orgs you have access to --> GET /v1/org_feed//users
More on Topic Security
Topic and Activity security are virtually the same. Users can follow topics and users can follow StreamWork activities. The only difference is that a user must be a participant of an activity to be allowed to follow an activity.
No matter who or what a person follows, they will never see events from topics that they do not follow. Events in a topic are only made available to people in that topic. In the case of topics, the application who owns the topic controls who can follow the topic. The follow action is only available to the client application that owns the topic. This allows the client application to control who sees the events that it publishes. The same goes for Activities. Activities are private and unless you are a participant of an activity you will never be able to see other people’s events from within that activity.
Posting events
When posting events to StreamWork you need to submit an Activity Streams (http://activitystrea.ms/ (http://activitystrea.ms/)) formatted XML fragment. As the API progresses StreamWork aims to be a generic Activity Streams reader, but until we get there I wanted to share information on just what we expect from the XML.
Like I mentioned above you should be posting new events to -->
POST https://streamwork.com/v1/user_feed/topics (https://streamwork.com/v1/user_feed/topics)
