IBM Connections Activity Stream APIs - Lab Dec 2012

1,655 views

Published on

Serie of 5 exercises introducing to the Activity Stream APIs. Initially presented for a session in December 2012 - sharing on SlideShare as providing overall overview on the APIs

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,655
On SlideShare
0
From Embeds
0
Number of Embeds
11
Actions
Shares
0
Downloads
24
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

IBM Connections Activity Stream APIs - Lab Dec 2012

  1. 1. Activity Streams APIs Lab session
  2. 2. 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
  3. 3. 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 | © 2012 IBM Corporation
  4. 4. 1. Fetching Activity Stream with RESTClient 4 | © 2012 IBM Corporation
  5. 5. 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 | © 2012 IBM Corporation
  6. 6. 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 | © 2012 IBM Corporation
  7. 7. Fetching Activity Stream with RESTClient 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 | © 2012 IBM Corporation
  8. 8. Fetching Activity Stream with RESTClient 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 | © 2012 IBM Corporation
  9. 9. Fetching Activity Stream with RESTClient 4. Examining the response from the server 9 | © 2012 IBM Corporation
  10. 10. 2. Posting a “simple” event to my own stream 10 | © 2012 IBM Corporation
  11. 11. Posting a “simple” event to my own stream Objective: Posting an event with static content to my own stream 11 | © 2012 IBM Corporation
  12. 12. 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 | © 2012 IBM Corporation
  13. 13. 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 | © 2012 IBM Corporation
  14. 14. 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" } } Actor 14 | © 2012 IBM Corporation
  15. 15. 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" } } Verb 15 | © 2012 IBM Corporation
  16. 16. 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" } } Object Note: objectType can be any string. Only the objectType “person” is recognized by the system for specific purposes (templating) 16 | © 2012 IBM Corporation
  17. 17. 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" } } Target 17 | © 2012 IBM Corporation
  18. 18. 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" }, { "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 | © 2012 IBM Corporation
  19. 19. 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" }, … {"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 | © 2012 IBM Corporation
  20. 20. Posting a “simple” event to my own stream 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 | © 2012 IBM Corporation
  21. 21. 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! 21 | © 2012 IBM Corporation
  22. 22. 3. Adding some “shiny” (title templating) 22 | © 2012 IBM Corporation
  23. 23. 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 | © 2012 IBM Corporation
  24. 24. Event title templating ■ 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 | © 2012 IBM Corporation
  25. 25. Event title templating 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 | © 2012 IBM Corporation
  26. 26. Event title templating 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 | © 2012 IBM Corporation
  27. 27. 4. Referencing an Embedded Experience Gadget 27 | © 2012 IBM Corporation
  28. 28. 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 | © 2012 IBM Corporation
  29. 29. 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 | © 2012 IBM Corporation
  30. 30. 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 | © 2012 IBM Corporation
  31. 31. 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 | © 2012 IBM Corporation
  32. 32. 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” 32 | © 2012 IBM Corporation
  33. 33. Registering an OpenSocial Gadget in Connections 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 | © 2012 IBM Corporation
  34. 34. Registering an OpenSocial Gadget in Connections 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 | © 2012 IBM Corporation
  35. 35. Registering an OpenSocial Gadget in Connections 5. Enable the widget by selecting it and clicking “Enable” 35 | © 2012 IBM Corporation
  36. 36. Registering an OpenSocial Gadget in Connections 6. Go to Homepage → My Page 7. Click Customize (top right) 8. The “Hello World” gadget should be available 36 | © 2012 IBM Corporation
  37. 37. 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. | © 2012 IBM Corporation
  38. 38. 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 | © 2012 IBM Corporation
  39. 39. 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 | © 2012 IBM Corporation
  40. 40. 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 | © 2012 IBM Corporation
  41. 41. 5. Distributing event to multiple users 41 | © 2012 IBM Corporation
  42. 42. Distributing events to other users Objective: ● Pushing the event to stream of multiple users 42 | © 2012 IBM Corporation
  43. 43. Distributing events to other 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. 43 | © 2012 IBM Corporation
  44. 44. Distributing events to other users 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 | © 2012 IBM Corporation
  45. 45. 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 | © 2012 IBM Corporation
  46. 46. 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 | © 2012 IBM Corporation

×