IBM Connections Activity Stream APIs - Lab Dec 2012

Activity Streams APIsLab session

2 | © 2012 IBM Corporation

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 APIsfor instance)

Push eventsto 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


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

https://addons.mozilla.org/en-US/firefox/addon/restclient/


1. Fetching Activity Stream with RESTClient


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


Set HTTP Headers on the request

HTTP Method

Target of the request

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

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



3. Our aim is to trigger a GET HTTP request to the following URL:

<ctxRoot>/opensocial/basic/rest/activitystreams/@me/@all/@all?rollup=true

User idThe 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

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

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

App id

Events for a given applications.

@all corresponds to top level view

Application name: “activities”, “blogs”, ...

<ctxRoot> is the context root of the OpenSocial end-point deployment on your VM

Authentication scheme

Specify the auth. Scheme intendend to be used:● “basic”: basic

authentication● “form”: form based

authentication● “oauth”

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

Replace <ctxRoot> with the hostname of your VM (including

port). Ie: https://qs.renovations.com:44

4/connections



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

Once done, RESTClientadds the (encoded) basicauth. credentials inthe header field of the request

Username: ablanksPassword: passw0rd



4. Examining the response from the server


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


Posting a “simple” event to my own stream

Objective: Posting an event with static content to my own stream


Semantic of an event

“Amy Blanks posted a new video to a channel”

■ 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

Actor Verb Object Target


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

http://www.youtube.com/watch?v=g8qbmhc59lY





Actor






Verb






Object

Note: objectType can be any string.

Only the objectType “person” is recognized by the system

for specific purposes (templating)






Target





{ "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" }, { "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





{ "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" }, … {"generator": { "image": {"url": "http://www.roomsxml.com/RXLFTP/images/youtube-logo.gif"}, ... }}

title

content

Object(summary)

Only some fields are rendered by the Connections Activity Stream UI – title, content

(HTML), object.summary field and generator.image field

Generator image




Posting a “simple” event to my own stream1. 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”


Posting a “simple” event to my own stream

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!


3. Adding some “shiny” (title templating)


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



■ 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)



3.1. Using object substitution to enhance the event title

● Replace the hardcode title string with the templated string below

● Post the new event as shown in exercise 2

{ ...

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

{ ...

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

...}

Hardcoded string Templated string

Note: Ex3-Templating1.txt contains the JSON document

with template if needed



3.2. Using full template substitution for internationalization purposes

● Replace the hardcode string with the full templated string

● Post the new event● You can change the browser locale to see the templated string in different

locales through Edit → Preferences → Languages

{ ...

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

{ ...

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

...}

Hardcoded string Templated string

Note: Ex3-Templating2.txt contains the JSON document

with template if needed


4. Referencing an Embedded Experience Gadget


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


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 (featureaccess, whitelist, ...)


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 type2. 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)


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

http://qs.renovations.com:9085/EE/HelloWorld.xml


Registering an OpenSocial Gadget in Connections■ 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”

https://qs.renovations.com:9047/admin



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



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”

http://qs.renovations.com:9085/EE/HelloWorld.xml



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



6. Go to Homepage → My Page

7. Click Customize (top right)

8. The “Hello World” gadget should be available

| © 2012 IBM Corporation

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

1. Require feature: “embedded-experiences”. 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().getDataSet(key) return an json object (name / value pairs) corresponding to the “context” defined in the event (more in next slides)

1

2

3

4


Referencing a EE gadget from the event

■ 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 throughopensocial.data.getDataContext().getDataSet(key)ie: opensocial.data.getDataContext().getDataSet(key)['videoId'] returns the “g8qbmhc59lY” in our example

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


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

http://qs.renovations.com:9085/EE/EEYoutube.xml


5. Distributing event to multiple users


Distributing events to other users

Objective:● Pushing the event to stream of multiple users



● 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.



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


Distributing events to other user

2. Add the following “to” JSON fragment to the event (after “openSocial”)

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

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

"to": [{"id": "0EE5A7FA-3434-9A59-4825-7A7000278DAA"}]

Note: Full JSON document is also available in file Ex5-

Distributing.txt


Resources

■ IBM Connections APIs:─ http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?

lookupName=IBM+Connections+4.0+API+Documentation#action=openDocument&content=catcontent&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

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



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



http://www.youtube.com/watch?v=9gW2YVBrNVA

https://www.ibm.com/developerworks/lotus/documentation/osgadgetconnections4/index.html

http://docs.opensocial.org/display/OSD/Specs

Technology

IBM Connections Activity Stream APIs - Lab Dec 2012