vincent burckhardt - exending connections with opensocial gadgets

OpenSocial Gadgets in IBM Connections Social Connections V - Zurich 28th June 2013

2 | © 2012 IBM Corporation

Agenda

■ Open standards and IBM's role■ OpenSocial Gadgets in Connections■ Basics of implementing and deploying an OpenSocial Gadget■ Advanced topics

─ OpenSocial “features”

─ Embedded Experience and Sharebox

─ Security

─ Best practices


Open standards, Open Social and IBM


IBM leads standardization of social business

A commitment to drive and leverage open standards:

─ Align platform capabilities with open standards … and introduce, extend/ push for new standards whenever needed

– Maximize choice, flexibility, and ease of integration– Proposing a development model where developers do not have to choose between

Connections and other social networking platforms

─ Leveraging existing skill sets by building on familiar technologies and architectures …

– Contributes to significantly reduce the time for a developer to get up to speed to work against Connections

─ Providing a consistent deployment model that spans traditional web to mobile applications

– Build unified end-user experience

– Consistent extensibility independent of the product, delivery model, and client type

HTML5 ARIA SAML

5 | © 2012 IBM Corporation5

The OpenSocial specifications are managed by the OpenSocial foundation, whose mission is to promote openness and interoperability of application in the “Social Business” area

What is it? Why is it important?

OpenSocial defines the specifications for:

● The container, which is the component hosting environment.The container is embedded in Connections 4.0 and provided out of the box.

● The APIs provided by the container covering a wide range of concerns:

● Client-side APIs – OpenSocial Gadgets

● Server-side REST APIs – People, Activity Stream

● Authorization - OAuth

OpenSocial is the primary way to transform Connections into an open social network platform.

General trend of OS is to go beyond initial goal of allowing 3rd

party content to run in the platform, by incorporating additional social-related

specifications (Activity Stream, Oauth, ...)

• IBM participates on the OpenSocial board of directors and is working to drive a three-year strategy with community members.

• Planned Implementations: SmartCloud, IBM Connections, IBM Lotus Notes/Domino, Rational Team Concert, Sterling

• Current Implementations: Cisco, SAP, Jive, Atlassian, Google, Yahoo, LifeRay, Oracle, Magneto, Tibco, Tibbr, Surfnet, Paypal

• Find out more about OpenSocial at www.opensocial.org

Standards Profile :


Open Social gadgets in Connections


OpenSocial Gadgets in Connections

■ OpenSocial Gadget specs used to define extension points across Connections:─ Sections of the Global Sharebox

─ EE experience gadgets

─ Homepage Widget page (“My Page”) and side bar

| © 2012 IBM Corporation

iWidgets vs OpenSocial Gadgets

iWidget OpenSocial Gadget

Activity Streams * X

Share Dialog X

Home Page X X

Profiles X

Communities X

Rendering inline iFrame

Specification iWidget 1.0 OpenSocial 2.5

■ Recommendation: Use an OpenSocial Gadget when possible● Provides better integration and code reuse opportunities with other products

– Example: IBM Notes / Domino 9

* Available in the following applications: Home Page, Profiles, Communities


Anatomy of an OpenSocial Gadget

1. <?xml version="1.0" encoding="UTF-8"?>2. <Module>3. <ModulePrefs title="Hello 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, preferred height/width, …)

6. Root of the content (HTML displayed to the end-user)Gadgets might have multiple views labelled with the “view” element


Anatomy of an OpenSocial Gadget■ User preferences

─ Name/value pairs

─ Supported data type: string, bool, enum, ...

─ Persisted by user in Connections

─ UI to edit pref. rendered by Connections for Homepage gadget

■ Internationalization─ XML files containing strings (key/value pairs)

per language

─ Strings are referenced by key in gadget XML, prefixed with __MSG_

■ Complex views─ Any standard HTML supported, as any

standard HTML page

─ … can load any JavaScript library (Dojo, jQuery, …)

<?xml version="1.0" encoding="UTF-8"?><Module> <ModulePrefs title="Gadget Example" width="400" height="100"> <Locale lang="de" messages="nls/de/message_ALL.xml"/> <Locale lang="en" messages="nls/en/message_ALL.xml" /> </ModulePrefs>

<UserPref name="color" display_name="__MSG_color_label__" default_value="blue" datatype="string" />

<Content type="html" view="default"><![CDATA[<script type="text/javascript"> gadgets.util.registerOnLoadHandler(function(){ var pref = new gadgets.Prefs(); var color = pref.getString("color"); document.getElementById("myDiv").style.color = color;});</script>

<div id="myDiv">Any HTML...</div>]]> </Content></Module>


Development tools and administration


Development environment

■ OpenSocial gadgets are 'just' XML, HTML, JS and CSS─ Pick your favorite IDE/text editor!

─ Eclipse with embedded Tomcat/Jetty to host gadget resources is perfectly sufficient

■ A few useful tools─ OSDE plugin for Eclipse (“OpenSocial Development Environment”) -

http://code.google.com/p/opensocial-development-environment/

– Integrated gadget development within Eclipse – generate boilerplate code for gadgets, GUI editors for gadget xml, comes with packaged Shindig to preview gadget, …

─ OSE (“OpenSocial Explorer) -http://opensocial.github.io/explorer/index.html

– Playground – comes with a number of samples that can be run. Allow editing gadget XML and resources inline and see result in real time. Great to learn more about gadget development.

http://code.google.com/p/opensocial-development-environment/

http://opensocial.github.io/explorer/index.html


The Boostrap page{yourServer}/connections/resources/web/com.ibm.lconn.gadget/test/bootstrap.html?render=test&oneui=3

opensocial-config.xml.. for developers

<developer enabled="true"

allowSSOFeature="true" allowIntranetProxyAccess="true"><developer-hosts-whitelist allServers="false"></developer-hosts-whitelist></developer>

■ Enables “developer” features including the “bootstrap” page

─ Allow gadget from whitelisted domain to be rendered without requiring administer level access to Connections

─ If developer-hosts-whitelist/[@allServers] is set to true, then all domain are allowed (in other words, no whitelist)

■ @allowSSOFeature and @allowIntranetProxyAccess control the proxy access

─ See “Security” Proxy access section later in this presentation


Gadget administration

■ Administrator can:─ Register/remove/disable gadgets

─ Gadgets are administrated through:

– Homepage Admin UI

– wsadmin commands

■ Prior to registration in Connections,the gadget resources (XML descriptor, JavaScript, CSS, images, ...) MUST be accessible by the OpenSocial container in Connections:

─ Resources deployed on a web server

─ Web server accessible from the container


Gadget specific registration settings

OpenSocial Gadgets specifics:

■ Security:

─ Control the level of feature access available to the registered gadget

─ Two main categories: “Restricted” and “Trusted” gadgets

─ See Security section later in this presentation for details

■ UI Integration points:

─ Indicate if the gadget is used in Share Dialog or as an Embedded Experience (Activity Stream)

■ Server access via Proxy:

─ Control the level of proxy access for the registered gadget – see dedicated security section later in this presentation

■ Service Mapping:

─ Map the gadget to a registered Oauth client

─ See step by step example in Security section


Registering an OpenSocial Gadget in Connections


Moving beyond the basics


OpenSocial gadget features

Feature Access – OpenSocial exposes a number of “features”. ■ Features are often just a JavaScript libraries allowing the gadget to leverage

specific capabilities─ (in certain cases – dramatically alter the behavior of the “container” - a key example of this is

“SSO”, which disables the Locked-Domains security feature)

■ Gadget developer declares which features are required in the gadget XML

■ As unrestricted feature access is dangerous, when an administrator “registers” a gadget, the specify the level of access that gadget receives

─ The container refuses to render the gadget is one of the required feature is not available

─ Features can be declared as being <Optional feature=”...”/>

– Gadget is rendered even if optional features are not available

– Tip: use gadget.util.hasFeature prior to using the JavaScript APIs to ensure the feature is actual available


OpenSocial Gadget features

■ Around 90 features in OpenSocial 2.5 specs + a few features specific to Connections

─ http://shindig.apache.org/documentation_features.html

■ IO and network related operations─ gadget.io.makeRequest

─ OSAPIs

─ Data pipelining

─ RPC

─ pub/sub

■ User preferences■ Templating■ UI functionalities

─ Opening popup, including to handle Oauth dance

─ Resizing gadget

■ “Utilities”─ JSON manipulation, DOM, logging, i18n

─ … you're usually better off using existing libraries (Dojo, jQuery) if you're already familiar with them

http://shindig.apache.org/documentation_features.html


Gadget API – IO operations

■ Making ajax request in a gadget: gadget.io.makeRequest─ Leverage server-side proxy (in container) to fetch content from remote servers on other domain

(based on access policies per gadget defined by administrator)

─ Support authentication scheme: basic auth, form based auth, Oauth 1 and 2

─ Response is cached for 2 hours by default

─ Avoid using XMLHTTPRequest (or toolkit wrappers based on top on it – such as dojo.xhr*)


Gadget APIs - Osapi

■ Background: OpenSocial defines a standard for server-side REST and RPC based APIs for common social capabilities

─ People, relationship, activities, groups, …

─ Connections 4.0+ implements a subset of the OpenSocial APIs:

– People

– ActivityStreams

■ Gadget feature “osapi” provides JavaScript utilities allowing to interact with these APIs

<Module> <ModulePrefs title="OSAPI Sample"> <Require feature="osapi" /> </ModulePrefs> <Content type="html"> <![CDATA[<script type="text/javascript"> gadgets.util.registerOnLoadHandler(function(){ osapi.people.get({"userId":"@viewer"}).execute( function(result) { document.getElementById("userName").innerHTML = result.displayName });});</script>

Hello <span id="userName"></span> ]]> </Content></Module>


Gadget APIs – Data pipelining

■ Declarative syntax allowing to specify remote data the gadget needed in advance

■ Container fetches/caches resources and send them along other gadget meta-data

─ Support OpenSocial APIs and remote HTTP resource

– <os:DataRequest method="people.get" userId="@viewer"/>

– <os:HttpRequest href="https://w3-connections.ibm.com/dogear/atom?sortBy=created&lang=en_us">

■ Benefits:─ Essentially performance

– Reduce the number of browser-server round trip on gadget load

– Use pipelining instead of makeRequest, osapi calls on gadget load

─ Templating – instruct container to generate dynamically HTML server-side using fetched data


Gadget APIs – Data pipelining

<?xml version="1.0" encoding="UTF-8"?><Module> <ModulePrefs title="data pipelining gadget"> <Require feature="opensocial-data" /> </ModulePrefs> <Content type="html"> <![CDATA[ <script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:DataRequest key="me" method="people.get" userId="@view" /> </script> <script type="text/javascript"> gadgets.util.registerOnLoadHandler(function(){ var me = opensocial.data.getDataContext().getDataSet("me");

document.getElementById("userName").innerHTML = me.displayName; }); </script> Hello <span id="userName"></span> ]]> </Content></Module>


Embedded Experience and Sharebox


Embedded Experience

■ Conceptually: Provide a way to interact dynamically with external content directly in context without having to switch to another application

─ Used in Connections and Notes 9 to bring external content in context in the Activity Stream and an email


Embedded Experience


Embedded Experience

■ Technically: A standard OpenSocial gadget that can access to contextual information

■ The “context” is passed to the gadget as a JSON payload (name/value pairs)─ Example {"videoId":"g8qbmhc59lY"}

─ In Connections Activity Stream, the context is included for each event in the Activity Stream

– (More details on the Activity Stream specifics in workshop materials: https://docs.google.com/viewer?url=http%3A%2F%2Fwww-10.lotus.com%2Fldd%2Fappdevwiki.nsf%2Fxsp%2F.ibmmodres%2Fdomino%2FOpenAttachment%2Fldd%2Fappdevwiki.nsf%2F82567C415DF5243185257AEE00626F82%2Fattach%2F5-sdk-workshop-activitystreams.pdf )

─ In Notes, the context is located in the header of the mail (MIME)

■ The gadget can access the “context” through JavaScript APIs available from the “embedded-experience” feature

─ Example for the payload above – the JavaScript call opensocial.data.getDataContext().getDataSet(key)['videoId'] returns the “g8qbmhc59lY”

https://docs.google.com/viewer?url=http://www-10.lotus.com/ldd/appdevwiki.nsf/xsp/.ibmmodres/domino/OpenAttachment/ldd/appdevwiki.nsf/82567C415DF5243185257AEE00626F82/attach/5-sdk-workshop-activitystreams.pdf






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


Sharebox

■ Sharebox can be open from anywhere in Connections through the “Share” button in header

─ Offers a quick way to create/share content from anywhere

─ “Status Updates” and “Files” sections provided out-of-the-box

■ Content of each section is defined by an OpenSocial gadget─ Can be extended with your own gadget


Sharebox example

<Module><ModulePrefs title="Sample Sharebox"><Require feature="actions"><Param name="action-contributions"> <![CDATA[ <actions> <action id="actionExampleId" path="container/sharebox" label="Sample Gadget" tooltip="Text appearing when hovering over the tab in the Sharebox" /> </actions> ]]></Param></Require></ModulePrefs><Content type="html" view="default"><![CDATA[<script type="text/javascript">var customAction = { id: "actionExampleId", callback: updateContext }; gadgets.util.registerOnLoadHandler(function() { gadgets.actions.updateAction(customAction); }); function updateContext(selection) { if(selection.type == "com.ibm.social.sharebox.context"){ // code to init the gadget from here... } } </script>

Some HTML displayed to the end-user...]]></Content></Module>

1. Extend the UI by contributing an “action” - contributed to the sharebox with through the path “container/sharebox”

2. Bind a Js callback function to the action with gadgets.actions.updateAction (invoked when user click the tab in the sharebox)

1

2


Sharebox■ The feature “ibm.connections.sharedialog” provides APIs for

extra capabilities around lifecycle:─ Lifecycle:

– Close the sharebox programmatically

– Detect when user close the sharebox

─ Interaction with sharebox:

– Mark state as dirty (ie: user has entered some information in your gadget but not saved yet)

– Prevent user from moving to another tab of the sharebox

─ Integration with rest of page

– Display info, warning, error message

■ See documentation athttp://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Optional_features_for_custom_sharing_gadgets_ic40&content=pdcontent

http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Optional_features_for_custom_sharing_gadgets_ic40&content=pdcontent




Security / Authorization


Oauth – Open Authorization

Standardized mechanism to delegate authorization● Authorize a service (“consumer”) to act on your behalf (“user”) in

another service (“provider”)● At no stage the consumer service has access to the provider's

credentials of the user

Implementations Include: Facebook, G+, Microsoft Windows Live, Office 365, Google, BBC, Opera, TypePad, Gowalla, Gnip, SocialCast, Superfeedr, Tibber, YIID, Cisco, Yammer, SAP, Jive, Atlassian, Yahoo, LifeRay, Oracle . . .

Consumer

Provider User

OAuth flow

Other

Legend

Send to Provider's auth. page

Action requiring to use provider's API

Redirect to consumerpage with unique code

Authenticate and authorize

Redirect to URL with code Exchange code for token

Send access (and refresh) token

API request with access token


Oauth – Open Authorization■ Connections is a “provider”

─ Any Connections API can be accessed through a Oauth token (with associated flow allowing a Connections user to grant access to his Connections data to a 3rd party)

■ … but also an Oauth “consumer” (OpenSocial container)─ The container handles most of the complexity of the Oauth dance and management of token for

your gadget

– Local caching of access and refresh token

– Pass access token to API calls to service provider

Connections page

Gadget

OpenSocialAPI

Connections (server-side)

Widget Container /

Shindig

Oauth token

Service Provider

Contacts

Calendar

documents

Protected Resources

Handle(most of)Oauthdance+ APIcalls withOauth token

gadget.io.makeRequest

Xhr callto container(security tokenSSO)



From a developer perspective...



Steps to deploy the gadget in Connections with a Oauth dependency1) Register your application with the provider to get a client id and secret

Client id and secret are used as part of Oauth dance



2) Register the details of the provider end-point in Connections● Oauth authorization page (where the user is directed to approve access)● Oauth token end-point (where the container exchange code with access token, in particular)

wsadmin>NewsOAuth2ConsumerService.registerProvider("googleAPI", "standard", "false", "true", "https://accounts.google.com/o/oauth2/auth", "https://accounts.google.com/o/oauth2/token")

3) Create a client (consumer) for the provider in Connections. ● The container will use these details to manage the Oauth dance with the provider● This is where you put the client id and secret obtained when registering your application with the

provider (step 1)

wsadmin>NewsOAuth2ConsumerService.registerClient("googleAPI_client1","googleAPI","confidential","code","798202498964.apps.googleusercontent.com","PgJ8FLZk88FAuqy7i9UQF8eb","https://{opensocial}/gadgets/oauth2callback")

4) Bind the gadget with the client from the gadget administration page

https://accounts.google.com/o/oauth2/token

https://accounts.google.com/o/oauth2/token


Security■ Feature restriction

─ “Restricted” gadgets do not have Oauth and SSO access and have limited interaction with the container (cannot open popup for instance, cannot save preferences)

─ “Trusted” gadgets can use Oauth and use all gadget features

– Still in a sandbox locked domain unless the “Use SSO” option is checked

■ Proxy access─ Configure per gadget level of proxy access

for gadget.io.makeRequest

■ Locked domains─ Feature for rendering gadgets in an iFrame that

is hosted outside of the SSO domain.

─ Gadget does not have access to:

– Any cookie, including SSO token

– Rest of the page (DOM)

– Servers on same domain as Connections deployment


Proxy Security

■ Proxy access─ Restrict hosts that can be accessed with

gadget.io.makeRequest

─ Comes in conjunction with locked domains (otherwise a simple ajax request can be made to any server on the same domain as your Connections deployment)

■ Options:─ Only outside the intranet

– What is inside and outside the intranet is determined by the WebSphere SSO domain

─ All server– Any server WebSphere can access can be

accessed by this gadget

─ Custom– Gadget has no implicit access

– Manually configured in proxy-policy.dynamic file

– See http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Configuring_perhost_proxy_access_rules_for_OpenSocial_gadgets_ic40&content=pdcontent

http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Configuring_perhost_proxy_access_rules_for_OpenSocial_gadgets_ic40&content=pdcontent







Locked domains

■ 2 main problems with 3rd party gadget (un/semi-trusted) :─ How do I prevent 3rd party gadget code from accessing the rest of the page (DOM)

─ How do I prevent 3rd party gadget code from performing Ajax requests on my intranet? (SSO domain)

■ Solution is to host iFrame on different host per gadget:Page: greenhouse.lotus.comIFrame: {unique-id-per-gadget}.gadgets.locked.comSSO: *.lotus.com

■ Host name for iFrame is not in SSO domain

■ Requires configuration─ DNS, IHS, Connections configuration, …

─ See http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Enabling_locked_domains_ic40&content=pdcontent

Gadget InLOCKED IFRAME

http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+documentation#action=openDocument&res_title=Enabling_locked_domains_ic40&content=pdcontent




Best practices■ All best practices in front-end development apply to

gadgets as well!─ Use a toolkit – Social Business Toolkit, Dojo, jQuery

■ Integrate nicely into Connections UI – including support for custom theme

─ Use <Optional feature="com.ibm.connections.theme"/> to inject Connections CSS (One UI) in gadget iFrame

─ One UI components and guidelines: http://infolib.lotus.com/resources/oneui/3.0/docPublic/index.htm

■ Remember you're in an iframe─ Limited real-estate – impact modal popups for instance (dijit.Dialog). Design gadget accordingly.

■ Performance: minimize network latency─ Minimize number of REST call - leverage pipelining and templating

─ Leverage content rewrite and proxy (gadgets.io.getProxyUrl()) to cache resources locally

■ Use gadget programmatic model whenever possible─ In particular for io - gadget.io.makeRequest (proxying, caching)

─ User preference, ...

■ Test your gadget with multiple combination of user preferences before deploying

http://infolib.lotus.com/resources/oneui/3.0/docPublic/index.htm

vincent burckhardt - exending connections with opensocial gadgets

Technology

0documentationactionopendocumentamp

activity stream

javascript

client id

home page

html displayed

lookupnameibmconnections4

wsadmingt