IBM Connections Activity Stream APIs - Lab Dec 2012

Activity Streams APIs
Lab session

Practice!
Imagine you had to implement a service listening to action from Youtube and
publishing them as events to Connections

Your service
Listen to actions
(through APIs
for instance)

Push events
to Activity Stream

In this lab session, we'll learn more about the Activity Stream APIs through a concrete
scenario of generating Youtube events:
● Basics of fetching Activity Stream data with RESTClient
● Pushing a basic event to your own stream
● Adding some “shiny” (templated title)
● Implementation an OpenSocial gadget displaying video from YouTube
● Using a Gadget as the Embedded Experience popup content
2 |

© 2012 IBM Corporation

Tool being used in this lab session
■
■

Any tool allowing to perform GET and POST HTTP request would do the job
RESTClient – plugin for Firefox
─ https://addons.mozilla.org/en-US/firefox/addon/restclient/
─ The plugin is already installed on your laptops

■

http://qs.renovations.com:9085/EE/ActivityStreamAPIsLab.pdf
3 |


1. Fetching Activity Stream with RESTClient

4 |


Fetching Activity Stream with RESTClient
Objectives:
●

Get familiar with RESTClient

●

Fetch Activity Stream feed corresponding to the “I'm Following” view in Homepage

1. Open Firefox on your VM and the RESTClient

2. A new tab opens up with RESTClient

5 |


Set HTTP Headers on the request

Target of the request
HTTP Method
Body content of the request
(for POST / PUT requests)

Detail of the response to the
request (headers and content
with various formatting options)

6 |



Replace <ctxRoot> with the
hostname of your VM (including
port). Ie:
https://qs.renovations.com:44
4/connections

3. Our aim is to trigger a GET HTTP request to the following URL:
<ctxRoot>/opensocial/basic/rest/activitystreams/@me/@all/@all?rollup=true

<ctxRoot> is the
context root of the
OpenSocial endpoint deployment on
your VM

Authentication scheme
Specify the auth. Scheme
intendend to be used:
●
“basic”: basic
authentication
●
“form”: form based
authentication
●
“oauth”

User id
The stream returns all
events that are related
to the given user.
@me is an alias
representing the
currently authenticated
user.
(“I'm Following” view in
the UI)

Group Id

App id

Events for the group
related to the user id.
@all (wild card) in most
cases.

Events for a given
applications.

@friends – events
from user network
@following – events
from people followed
@self – own events

@all corresponds to
top level view
Application name:
“activities”,
“blogs”, ...

3.1. Set the HTTP method to GET (we're fetching/getting data from the server)

7 |


3.2. Input basic authentication credentials to be used when sending the request
(RESTClient transforms and passes them as request headers under the hood)
Username: ablanks
Password: passw0rd

Once done, RESTClient
adds the (encoded) basic
auth. credentials in
the header field of the request
8 |


4. Examining the response from the server

9 |


2. Posting a “simple” event to my own stream

10 |


Posting a “simple” event to my own stream
Objective: Posting an event with static content to my own stream

11 |


Semantic of an event
“Amy Blanks posted a new video to a channel”
Actor

Verb

Object

Target

■

actor: Entity performing the activity (for instance, “Amy”)

■

verb: Action of the activity (for instance, “post”-ing)

■

object: The primarity object of the action (for instance, “video”)

■

target: Target of the action (for instance, “a channel”)

■

■

Activities/events can be represented in 2 formats:
─ JSON document
─ ATOM document
JSON is the primary format supported by Connections. Atom is only supported
on retrieval – not to post events

12 |


JSON representation of an activity
{
"actor": {
"id": "@me"
},
"verb": "post",
"title": "Amy posted the video IBM Connections 4 Homepage to the IBM channel.",
"content": "<b>Access the video by clicking on the thumbnail.</b>
<a href='http://www.youtube.com/watch?v=g8qbmhc59lY'>
<img src='http://img.youtube.com/vi/g8qbmhc59lY/default.jpg'/></a>
",
"object": {
"summary": "IBM Connections 4 Homepage Demo",
"objectType": "video",
"id": "youtube:video:g8qbmhc59lY",
"displayName": "IBM Connections 4 Homepage",
"url": "http://www.youtube.com/watch?v=g8qbmhc59lY"
},
"target": {
"summary": "IBM Channel",
"objectType": "channel",
"id": "youtube:channel:IBM",
"displayName": "IBM YouTube Channel",
"url": "http://www.youtube.com/user/IBM"
}
}

JSON document

13 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
"target": {
}
}

Actor

14 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
"target": {
}
}

Verb

15 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
"target": {
}
}

Object

Note: objectType can be any
string.
Only the objectType “person”
is recognized by the system
for specific purposes
(templating)

16 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
"target": {
}
}

Target

17 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
"target": {
},
{
"generator": {
"image": {"url": "http://www.roomsxml.com/RXLFTP/images/youtube-logo.gif"},
"id": "Youtube",
"displayName": "Youtube",
"url": "http://www.youtube.com/"
}
}

Generator field is optional (but
good practice to use): specify
information about the application
generating the event

18 |


{
"actor": {
"id": "@me"
},
"verb": "post",
",
"object": {
},
…
{"generator": {
"image": {"url": "http://www.roomsxml.com/RXLFTP/images/youtube-logo.gif"},
...
}
}

Only some fields are rendered
by the Connections Activity
Stream UI – title, content
(HTML), object.summary field
and generator.image field

title
content

Generator
image

Object
(summary)
19 |


1. Open Firefox and RESTClient
2. Set your credentials (basic authentication) (ablanks / passw0rd)
3. We're going to POST to the following URL (user's own feed):
<ctxRoot>/opensocial/basic/rest/activitystreams/@me/@all/@all

4. The content of the POST is a JSON fragment – we must specify this to the server through
a request header

4.1. Go to “Header → Custom Header”
4.2. Input the following:

Name: “Content-Type”
Value: “application/json”

20 |


5. Copy-paste the JSON document to the “body” field of RESTClient
● JSON document is located in the file Ex2-PostingSimpleEvent.txt

6. Press “Send” to post the event!
21 |


3. Adding some “shiny” (title templating)

22 |


Event title templating
Objectives:
● Use template support to:
●

Enhance the title of the event (business card on person name and links on object)

●

Internationalize the event title string

23 |


■

Connections allows for the introduction of two kinds of title template
─ Object substitutions - where an appropriate representation of a known object within the event is
substituted into the title.
─ Title template substitutions - these use the above object substitutions, providing a full title that is
appropriately resourced.

■

Object Substitution. Number of substitution values are supported within a
submitted event.title:
─ ${Actor} - this is converted into appropriately marked up HTML which displays the Actors name
and links to a Business Card corresponding to the Actor
─ ${Object} - if this is a person we display as with the Actor above, otherwise the displayName with
a link to the url
─ ${Target} - if this is a person we display as with the Actor above, otherwise the displayName with
a link to the url

■

Title Template Substitution. Particular text appropriate for the locale of the
viewing user is used when retrieving the event
─ ${add}=${Actor} added ${Object}.
─ ${add.target}=${Actor} added ${Object} to ${Target}.
─ .... (refer to API documentation for full list)

24 |


3.1. Using object substitution to enhance the event title
●

Replace the hardcode title string with the templated string below
Hardcoded string

{
...

"title": "Amy posted the video
IBM Connections 4 Homepage
to the IBM channel.",

...
"title": "${Actor} posted the video ${Object} to the
${Target}.",

...
}

●

Templated string

{

...
}

Post the new event as shown in exercise 2

Note: Ex3-Templating1.txt
contains the JSON document
with template if needed

25 |


3.2. Using full template substitution for internationalization purposes
Replace the hardcode string with the full templated string

●

Hardcoded string

{
...

Templated string

{
...

"title": "Amy posted the video
IBM Connections 4 Homepage
to the IBM channel.",
...
}
●
●

"title": "${post.target}",
...
}

Post the new event
You can change the browser locale to see the templated string in different
locales through Edit → Preferences → Languages
Note: Ex3-Templating2.txt
contains the JSON document
with template if needed

26 |


4. Referencing an Embedded Experience Gadget

27 |


Referencing an EE gadget
Objective:
● Understanding the basics of OpenSocial Gadget
● Registering an OpenSocial Gadget as an Homepage gadget
● Registering an OpenSocial Gadget as an EE gadget

28 |


OpenSocial Gadgets in Connections
■

OpenSocial Gadget specs used to define extension points across Connections:
─ Homepage Widget page (“My Page”) and side bar
─ Sections of the Global Sharebox
─ EE experience gadgets

■

Administrators can:
─ Register/remove/disable gadgets
─ Gadgets are administrated through:
– Homepage Admin UI
– wsadmin commands

■

opensocial-config.xml offers
additional config options:
─ Enable “developer” mode
─ Advanced security options (feature
access, whitelist, ...)

29 |


Anatomy of an OpenSocial Gadget

1. <?xml version="1.0" encoding="UTF-8"?>
2. <Module>
3. <ModulePrefs title="Hello EE World"
4.
description="Hello World gadget"
height="400" width="500">
5. </ModulePrefs>
6. <Content type="html" view="default">
7. <![CDATA[
8.
Hello World!
9. ]]></Content>
10. </Module>

1. XML version doc type
2. Root of the gadget definition (a
“module”)
3. Gadget preferences (title,
description, prefered
height/widget, …)
6. Root of the content (HTML
displayed to the end-user)

30 |


Registering an OpenSocial Gadget in Connections
Prereqs:
● The Gadget XML descriptor file is accessible from HTTP.
This is already done on your Vms – you can try to access the file from a web
browser at:
http://qs.renovations.com:9085/EE/HelloWorld.xml
● You are logged as a user mapped in the JEE “admin” role in Homepage
application

31 |


■

Mapping a user as admin in Homepage:

1) Go to the WebSphere administration console:
https://qs.renovations.com:9047/admin
2) Log as admin / passw0rd
3) Expend Applications → Application Types → WebSphere enterprise applications

4) In WebSphere enterprise application page, click Homepage (link)

5) Click “Security role to user/group mapping” (under “Detail Properties”)
6) Select the checkbox next to the J2EE role “admin“ and click “Map Users...” button
7) In “Search string” field, type “ablanks” and click “Search”

32 |


8) Select “AmyBlanks” in the select field named “Available” and click the → arrow

9) Click ok to validate (two forms) and then “Save”

10) Logout from WebSphere admin console by clicking the “logout” button
33 |


1. Log in as Amy Blanks in Connections (admin user in Homepage)
2. Click Homepage → Administration
3. Select “Add another widget”

4. Select “Open Social Gadget” as widget type

●

Input name “Hello World” in Widget Title

●

Input url to the xml descriptor of the OpenSocial gadget in “URL Address”
Url is http://qs.renovations.com:9085/EE/HelloWorld.xml
Tick the box “Display on the Widget page”
●

●

●

Leave any other form fields at their default value

●

Click “Save”
34 |


5. Enable the widget by selecting it and clicking “Enable”

35 |


6. Go to Homepage → My Page
7. Click Customize (top right)
8. The “Hello World” gadget should be available

36 |


Gadget specific registration settings
■

Widget Type:
─ Indicate if you are registering a gadget or iWidget

■

Security:
─ Indicate if this is a “restricted”, “trusted” or SSO gadget
─ Although the term is “trusted” trusted gadgets are still
“locked”
─ SSO access has major security implications and breaks
all of the security features of the product

■

UI Integration points:
─ Indicate if this gadget is intended for use in the
ActivityStream or Share Dialog
─ Note: this setting has additional security implications for
“feature access”

■

Server access via Proxy:
─ After the SSO box this is the most important security
feature.
─ For simplicity this setting, can either:
–

Open up all servers

–

Restrict access to servers not in the SSO domain
(Only out side the intranet

–

The custom setting gives the gadget no access.
With this, you must enumerate the server access.
|


Using an OpenSocial gadget to define the EE
<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="YouTube EE" description="YouTube EE" height="300"
width="500">
<Require feature="embedded-experiences"/>
</ModulePrefs>
<Content type="html" view="embedded, default"><![CDATA[
// (omitted) Code to load YouTube JavaScript API code

1

2

<script type="text/javascript">
var context;
function _runVideo(videoId) {
// (omitted) Render the YouTube player for videoId
}

3

function init(){
opensocial.data.getDataContext().registerListener('org.opensocial.ee.context',
function(key) {
context = opensocial.data.getDataContext().getDataSet(key);
var videoId = context['videoId'];
_runVideo(videoId);
}

});

gadgets.util.registerOnLoadHandler(init);
</script>
<div>
<h3>Video Viewer</h3>
<div id="videoDiv">Loading...</div>
</div>
]]></Content>
</Module>

4

1. Require feature: “embeddedexperiences”. Indicates to the
container to load JavaScript
resources/API specific to the EE
view
2. View = “embedded”. If this view is
defined, then it is the view being
rendered in the EE popup.
3. Init(): main function of our gadget.
Function is registered through
gadgets.util.registerOnLoadHandler
so that it is executed by the gadget
container when the gadget is open
4.
opensocial.data.getDataContext().get
DataSet(key) return an json object
(name / value pairs) corresponding to
the “context” defined in the event
(more in next slides)
38 |


Referencing a EE gadget from the event
■

"openSocial":
{
"embed": {
"gadget": "<url to XML file>",
"context":
{"videoId":"g8qbmhc59lY"}
}
}

It's simply a matter of pointing to the XML file
(HTTP accessible) in
openSocial.embed.gadget field when
POSTing the event
─ Important: For security reason, the referenced
gadget MUST be registered (added to “whitelist”)
through Homepage admin

■

openSocial.embed.context field contains the
“context” in which the OpenSocial Gadget is
rendered
─ This is simply additional data that is passed to the
OpenSocial Gadget when it is opened
─ In the case of the YouTube gadget, we pass the
“videoId”
─ The gadget code can access the context through
opensocial.data.getDataContext().getDataSet(key)
ie:
opensocial.data.getDataContext().getDataSet(key)
['videoId'] returns the “g8qbmhc59lY” in our example
39 |


Referencing a EE gadget from the event
Some practice...
1. Register the YouTube Gadget through Homepage admininistration UI
● Located on your VM at http://qs.renovations.com:9085/EE/EEYoutube.xml
● Similar as for the Hello World gadget in Homepage earlier. Only difference:
●

Make sure you check “Show for Activity Stream events” (in other words: allow to use the gadget
as EE)

2. Add the openSocial.embed fragment in previous slide to the
JSON event data
3. Post the new event to the stream

Note: Full JSON document
with EE is also available in file
Ex4-ReferencingEE.txt

40 |


5. Distributing event to multiple users

41 |


Distributing events to other users
Objective:
● Pushing the event to stream of multiple users

42 |


●

{

Posting to multiple users is done through the following fragment in the event (“mail box” model):
...

"to":[
{"id":"personId"},
{<... additionalPeople ...>}
]}
●

●

To avoid spam – normal users do not have the right to distribute events to other users steam
Special user (user in “trustedExternalApplication” J2EE role in WidgetContainer app) can deliver to
anyone
Posting to other steams can also be done by substituting the userId placeholder on POST

<ctxRoot>/opensocial/basic/rest/activitystreams/<userId>/@all/@all
●

Some basic rules:
1) To [UserID] where the user in question is the current user
2) To @me which resolves to the same thing
3)

To @public which means the event will appear on everyones discovery tab - but this is
only permitted if the submitting user is also the actor in the event

4)

To [CommunityId] where the current user is a member of that community or the
community is public - again this is only permitted if the submitting user is also the actor in
the event.
43 |


1. Remember – the event poster must be a user mapped in
trustedExternalApplication role in WidgetContainer application
─ This is already done on your VMs
─ From WAS admin console: Applications → WebSphere enterprise applications →
WidgetContainer → Security role to user/group mapping

44 |


Distributing events to other user
2. Add the following “to” JSON fragment to the event (after “openSocial”)
"to": [{"id": "0EE5A7FA-3434-9A59-4825-7A7000278DAA"}]

The id is the external id of user Frank Adams on your VMs

Note: Full JSON document is
also available in file Ex5Distributing.txt

3. Post (using url @me/@all/@all/ as previously)
4. You can log in as user Frank Adams with login fadams – passw0rd to see the
event

45 |


Resources
■

IBM Connections APIs:
─ http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?
lookupName=IBM+Connections+4.0+API+Documentation#action=openDocument&content=catc
ontent&ct=prodDoc

■

OpenSocial APIs in Connections
─ http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?
lookupName=IBM+Connections+4.0+API+Documentation#action=openDocument&res_title=IBM
_Connections_OpenSocial_API&content=pdcontent

■

Opensocial Gadget video tutorial:
─ http://www.youtube.com/watch?v=9gW2YVBrNVA

■

Developing OpenSocial gadgets for IBM Connections 4.0
─ https://www.ibm.com/developerworks/lotus/documentation/osgadgetconnections4/index.html

■

OpenSocial specifications
─ http://docs.opensocial.org/display/OSD/Specs

46 |


IBM Connections Activity Stream APIs - Lab Dec 2012

Recommended

Recommended

More Related Content

What's hot

What's hot (10)

Viewers also liked

Viewers also liked (6)

Similar to IBM Connections Activity Stream APIs - Lab Dec 2012

Similar to IBM Connections Activity Stream APIs - Lab Dec 2012 (20)

Recently uploaded

Recently uploaded (20)

IBM Connections Activity Stream APIs - Lab Dec 2012