JMP103 : Extending Your Application Arsenal With OpenSocial
Yun Zhi Lin, IBM China Investment Company Limited; Ryan Baxter, IBM
OpenSocial. You have heard the hype, maybe you have even seen the demos, but what is all the fuss about? This is your chance to get all your questions answered. In this session we’ll not only teach you about OpenSocial and how IBM is using it to enable exciting new features in IBM Notes and Domino Social Edition, IBM Connections, and IBM Connections Mail, but how you can use it to enhance your applications. You’ll walk away from this session armed with the knowledge to build compelling social apps and all the code you need to get started!
Sun, 26/Jan 08:00 AM – 10:00 AM
2. Please Note
IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM’s sole
discretion.
Information regarding potential future products is intended to outline our general product direction and it should not be
relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment, promise, or legal obligation to deliver
any material, code or functionality. Information about potential future products may not be incorporated into any contract.
The development, release, and timing of any future features or functionality described for our products remains at our sole
discretion
Performance is based on measurements and projections using standard IBM benchmarks in a controlled environment.
The actual throughput or performance that any user will experience will vary depending upon many factors, including
considerations such as the amount of multiprogramming in the user’s job stream, the I/O configuration, the storage
configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve
results similar to those stated here.
2
4. About Us
4
IBMer for 5 years
OpenSocial (and open source) enthusiast
Notes Java UI APIs, IBM Social Business Toolkit
@ryanjbaxter, http://ryanjbaxter.com
IBMer for 7 years
Notes Widgets and OpenSocial developer
XPages and Eclipse plugin development
6. OpenSocial
6
Social APIs and Mini Applications
(Gadgets)
IBM has a leadership role including
–
On the Board of Directors
–
Committers on Apache Shindig
–
Has been instrumental in drafting
the OpenSocial 2.0 & 2.5
specification
–
Invented and gave to the
community Embedded
Experiences and many, many
more capabilities
–
Provided enterprise extensions
Implementations Include: Cisco, SAP, Jive,
Atlassian, IBM SmartCloud, Google,
Yahoo, MySpace, LifeRay, Oracle,
Magneto, Tibco Tibbr, Surfnet, Paypal . . .
SmartCloud, IBM Connections, IBM
Notes/Domino®, Rational Team ConcertTM,
Sterling, IBM Business Process Manager...
7. Why Use OpenSocial?
IBM sees value in OpenSocial because it offers two very important things to IBM, its
partners, and its customers
–
An application model based on modern web standards that easily isolates third party
code
–
APIs for interacting with and creating social data (we still have a long way to go with
this one)
Cross product integration with Notes, iNotes, and Connections
–
Integrate your application into one or all of these products
–
Stand-alone (web) applications
–
Embedded within an envelope, i.e., email or activity entry
–
7
Access to social data and data models from Connections and SmartCloud
–
Connections 4 activity streams API
–
SmartClouds person and contacts APIs
8. Sample Gadget XML
<?xml version="1.0" encoding="UTF-8" ?>
<Module specificationVersion='2'>
<ModulePrefs title="Acme Airlines">
<!-- Features provide sets of functionality to the gadget
<Require feature="dynamic-height" />
<Require feature="embedded-experiences" />
</ModulePrefs>
<!-- Content sections are the UI of the gadget -->
<Content type="html" view="default, home">
<![CDATA[
<!--HTML, CSS, and JavaScript go here -->
]]>
</Content>
<Content type="html" view="embedded" href="ee.html"></Content>
</Module>
8
-->
9. The Basics
9
ModulePrefs
–
The gadget's ModulePrefs element contains basic information about the gadget
●
Title, author, description, icon
●
Features are also placed in the ModulePrefs element
– Features provide a set of functionality and sometimes APIs to the gadget
●
Message Bundles can be added to provide translated strings for your gadget
Content Sections
–
Content sections contain the UI and business logic for your gadget
●
You can have multiple content sections in one gadget XML
●
The HTML, CSS, and JavaScript of your gadget can either be inside the content
section or externally in a separate file
–
Different content sections can be distinguished via the view attribute
10. Gadget Views
10
Gadget views originally were used to distinguish between the amount of real-estate
available to a gadget
–
Home = little real-estate
–
Canvas = large amount of real-estate
Since OpenSocial 2.0 we have been moving more towards views indicating different uses
–
Embedded view for embedded experiences
–
Dialog views for when a gadget is opened in a dialog
Content sections with the same view name will be concatenated together
Gadgets can switch views programmatically and find out what view is currently rendered
–
gadgets.views.requestNavigateTo(viewName)
–
gadgets.views.getCurrentView()
11. Gadget Preferences
11
Any application is likely to have user preferences
to allow the user to customize portions of the
application
Gadget preferences are specified in UserPref
elements in the gadget XML
–
Strings, Booleans, Enums, and Lists all
specified in the type attribute
–
Display name attribute shows in the UI
–
Name attribute can be used to access the
preference within your code
–
You can also set a default value for a
preference
Get and set preferences via gadgets.Prefs
–
Require the feature setpefs when setting
preferences
13. Developing OpenSocial Gadgets
13
The first step to building OpenSocial gadgets is setting up a development environment
OpenSocial Explorer
–
An open source project from the OpenSocial Foundation meant to help developers get
started building OpenSocial gadgets.
–
Contains sample gadgets and allows developers to modify and create new gadgets
IBM Social Business Toolkit Playground
–
You can do everything you can do in the OpenSocial Explorer within the
Playground...and MORE!
–
Contains all the same samples plus sample gadgets that show how to integrate with
SmartCloud and Connections
–
Easily test your embedded experiences in emails and activity stream entries
17. Getting Started Writing JavaScript
17
Use your favorite JavaScript library
Just like any other web app you don't want to begin running your business logic before the
app has completely loaded
gadgets.util.registerOnLoadHandler(function)
–
When the function passed to this API is called the gadget has completely loaded
–
Similar to JQuery and Dojo's ready functions
–
You can use those instead if you are using those libraries
18. Making REST API Calls
All web applications need to make some kind of API calls and gadgets are no different
Use gadgets.io.makeRequest
–
Asynchronous
–
Takes a URL, parameters object, and callback function
–
Supports OAuth endpoints
–
DO NOT USE OTHER LIBRARIES' XHR METHODS
var params = {};
params[gadgets.io.RequestParameters.METHOD]
=gadgets.io.MethodType.GET;
params[gadgets.io.RequestParameters.CONTENT_TYPE]=gadgets.io.C
ontentType.JSON;
var callback = function(response){
...
};
gadgets.io.makeRequest('http://example.com/api/foo', callback,
params);
18
19. OAuth
OpenSocial uses OAuth for making protected API calls
–
Support for OAuth 1.0a and 2.0
OAuth stands for OPEN AUTHORIZATION not OPEN AUTHENTICATION
–
Authentication technologies may be used when authorizing
OAuth is very easy to use within a gadget, most of the hard work is done by the container
Use makeRequest and simply specify which OAuth version to use
The OAuth services used within the gadget need to be registered with the container
Request
Acme Gadget
Approval
19
Browser
Do you want to allow
Acme Gadget access
to your data?
YES NO
20. OAuth 1.0a in The Gadget XML
Service name must match what is registered in the container
URLs come from the provider you are authenticating with
<OAuth>
<Service name="my service">
<Request url="http://provider.com/authorize"/>
<Access url="http://provider.com/accessToken"/>
<Authorization url="http://provider.com/authorize"/>
</Service>
</OAuth>
20
21. OAuth 1.0a in The Gadget XML
Service name must match what is registered in the container
URLs come from the provider you are authenticating with
<OAuth>
<Service name="my service">
<Request url="http://provider.com/authorize"/>
<Access url="http://provider.com/accessToken"/>
<Authorization url="http://provider.com/authorize"/>
</Service>
</OAuth>
21
22. OAuth 2.0 in The Gadget XML
OAuth 2.0 is simpler, all URLs are configured on the container.
–
Service name needs to match what you register in the container
–
Scope indicates the API set you plan on accessing
<OAuth2>
<Service name="service name" scope="ProviderScope">
</Service>
</OAuth2>
22
23. Using OAuth in makeRequest
In the parameters passed to makeRequest indicate you are using OAuth 1.0a or 2.0
–
gadgets.io.AuthorizeType.OAUTH2
–
gadgets.io.AuthorizeType.OAUTH
–
23
Require the feature “oauthpopup”
–
This feature can be used to open the popup window for the user to enter their
credentials
–
Lets the gadget know when the OAuth dance is complete
24. OAuth makeRequest Example
var params = {};
params[gadgets.io.RequestParameters.AUTHORIZATION] =
gadgets.io.AuthorizationType.OAUTH2;
params[gadgets.io.RequestParameters.OAUTH_SERVICE_NAME] = 'serviceName';
gadgets.io.makeRequest('url', function(response) {
if (response.oauthApprovalUrl) {
var onOpen = function() {};
var onClose = function() {};
var popup = new gadgets.oauth.Popup(response.oauthApprovalUrl, null, onOpen,
onClose);
var click = popup.createOpenerOnClick();
click();
} else if (response.data) {
//We have data so lets use it!
} else {
gadgets.error('something went wrong');
}
}, params);
24
25. Interacting With The Container
25
As of OpenSocial 2.0 gadgets can now interact with the container they are rendered in
–
WARNING: These may not be supported completely in all containers - even every IBM
Container
Breaking Out Of The Box
–
Gadgets are rendered in an iFrame and they used to be confined to that frame in the
browser
–
With the open-views APIs gadgets can render other gadgets and URLs in new tabs,
windows, dialogs, etc
Contributing To The UI
–
Action contributions allows your gadget to contribute to the toolbar and menus of the
container
–
This is very similar to action contributions in Eclipse plugin development
Understanding What Is Selected
–
Gadgets can also listen for selection in Notes and iNotes
–
Emails, Contacts, and Files
27. Embedded Experiences
27
Changing the way you get notifications
–
The goal is to make notifications more useful and interactive
–
Supported in email and activity streams
●
IBM Connections, IBM Connections Mail, IBM Notes 9, IBM iNotes 9
●
JSON + XML
29. Notifications With Embedded Experiences
Activity
Entry
Action
Taken In
Your App
EE Data
Model
Gadget
Standard
MIME
Email
Your App
29
30. Something Of Importance Took Place!
Embedded experiences are almost always
generated due to an action that took place in
an app
–
Someone completed a task
–
Someone sent a survey to a group of
people
–
A travel request was submitted
–
A lead was entered in a CRM system
–
30
Now that the action took place you want to let
a group of people know about it
–
BE SOCIAL!
Your APP
Action Taken
In App
31. How do you want to let people know about it?
Traditionally emails were sent
–
Still applicable today, many apps still do this
In a social network, emails are not the primary
medium for communication
–
Almost all social networks have an activity
stream so we should post it there
Gadget EE
{
“gadget” : “http://acme.com/gagdet.xml”,
“context” : {
“id” : 123
}
}
URL EE
{“url” : “http://domino.com/myxpage.xsp”}
31
Activity Entry
EE Data
Model
Standard MIME
Email
32. Active Notifications
With embedded experiences,
notifications are no longer static
–
Active content allows your
notifications to never go stale and
always be up to date
Gadget
–
–
No need to leave your client, stay
where you are and get your work
done
–
32
The data used in your notifications is
unlimited, you have access to anything
Your App
33. Email Embedded Experience
From: notifications@socialnetwork.com
To: johndoe@example.com
Subject: Social Network: Mary Has Commented On Your Status
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="XXXXboundary text"
Mary has commented on your status.
--XXXXboundary text
Content-Type: text/plain
Mary has commeneted on your status.
--XXXXboundary text
Content-Type: text/html
<html>
<!-- HTML representation here -->
</html>
--XXXXboundary text
Content-Type: application/embed+json
{
"gadget" : "http://www.socialnetwork.com/embedded/commentgadget.xml",
"context" : 123
}
33
37. How Does OpenSocial Integrate Into IBM Connections?
37
Leveraging the existing widgets framework
–
OpenSocial is just a new type of widget, just like iWidgets
OpenSocial gadgets available on your homepage
–
In the activity stream
–
On the right hand side of your activity stream homepage
–
In the “My Page” of your homepage
Connections Mail supports embedded experiences in email
OpenSocial gadgets can also extend the share box
–
Allows you to integrate other sharing capabilities right into Connections
Connection's REST API and data model follows the OpenSocial standard
OpenSocial gadgets can interact with their containers
–
Contribute actions for ShareBox integration
–
Open itself, Embedded Experiences, and URLs as dialogs
38. Activity Streams Keep Your Users Up To Date
38
REST API and data model backed by the
OpenSocial standard
–
JSON data model - easy to use in your web
apps
3rd party apps can post entries to the activity
stream
–
Inside and outside of Connections
Integrate the Connections activity stream into
your apps
–
This is how we integrate the activity stream
into Notes
–
If your app is an OpenSocial container you
can render embedded experiences too!
39. Extending The Share Dialog
39
The share dialog allows you to share content
from anywhere in Connections
–
By default you can update your status or
upload a file
The share dialog is extensible using OpenSocial
gadgets
–
Take advantage of OpenSocial's actions
feature
40. Connections Mail
40
Connections Mail, like Notes and iNotes, supports embedded experiences as well
The same embedded experience you build for the activity stream will work in mail
41. Deploying OpenSocial Gadgets In Connections
41
Only Homepage admins can deploy gadgets
Gadgets must be added to the widget catalog
in Connections
–
Security
●
Restricted or Trusted (SSO)
–
UI Integration points for the Share dialog
–
Proxy access
●
Only outside the intranet
●
Everything
●
Custom
–
OAuth service mappings
42. Registering OAuth Clients For Gadgets In Connections
42
You must register OAuth clients for gadgets to use in Connections if a gadget is using OAuth
–
This is a two step process done via the wasadmin console, you must register an OAuth
provider and then register an OAuth client
●
A provider may be used by multiple clients. For example Google, Facebook,
Twitter, DropBox etc.
– wsadmin>NewsOAuth2ConsumerService.registerProvider("provider123",
"standard", "true", "false", "http://example.com/oauth/authorization",
"https://example.com/oauth/token")
●
A client gets bound to a gadget and points to a provider.
– You specify the client ID and secret obtained from the provider for your gadget
– wsadmin>NewsOAuth2ConsumerService.registerClient("client123",
"provider123", "confidential", "code", "my-client", "my-secret",
"https://connections.com/connections/opensocial/gadgets/oauth2callback")
After the clients have been registered you can bind them via wsadmin commands or via the
Homepage administration UI
45. How Does OpenSocial Integrate Into IBM Notes and iNotes?
●
45
Leveraging the existing My Widgets framework
–
OpenSocial is just a new type of widget, just like Google Gadgets or Web Page widgets
OpenSocial gadgets are available in both Notes and iNotes
–
In the sidebar
–
In tabs
–
In floating (modeless) windows
–
In new windows (Notes only)
–
In Mail as Embedded Experiences
Wire LiveText to OpenSocial gadgets
–
The recognized content is passed through gadget preference
–
By default launches in a floating window
–
Can be configured to open in tab, sidebar or new window
46. How Does OpenSocial Integrate Into IBM Notes and iNotes?
46
OpenSocial gadgets can interact with their containers
–
Contribute actions
●
To top-level menus and toolbars in Notes
●
To the context menu for mail messages, contacts, attachments (Notes only), and
LiveNames (Notes only)
–
Contribute OpenSearch search engines to the Notes search center
–
Listen for and publish selection
–
Open itself, Embedded Experiences, and URLs in new windows, tabs, floating windows
and the sidebar
47. OpenSearch
Use OpenSearch APIs to contribute to the Notes search center
<Optional feature="opensearch">
<Param name="opensearch-description">
<![CDATA[
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" >
<ShortName>CNN.com</ShortName>
<Description>CNN.com Search</Description>
<InputEncoding>UTF-8</InputEncoding>
<SearchForm>http://search.cnn.com/</SearchForm>
<Url type="text/html" method="get"
template="http://www.cnn.com/search/?query={searchTerms}">
</Url>
</OpenSearchDescription>
]]>
</Param>
</Optional>
47
More information in the OpenSocial spec
–
http://opensocial-resources.googlecode.com/svn/spec/2.5/CoreGadget.xml#OpenSearch
48. Creating OpenSocial Widgets in Notes and iNotes
●
48
Notes client provides wizards to create OpenSocial Widgets from gadgets
49. Managing OpenSocial Widgets in Notes and iNotes
●
49
Widget Catalog database is used to manage OpenSocial Gadgets in Notes and iNotes
–
OpenSocial widget is not usable until it's published to catalog and approved by
administrator
During the approval process, administrators will configure
–
Proxy settings – required
–
OAuth consumer information – required only if a gadget need them
A secure credential store database is used to manage sensitive information
50. Creating Widgets for URL Embedded Experience in
Notes/iNotes
50
You need to create a Web Page widget and enable it for embedded experiences
–
Make the Embedded Experiences URL generic to accommodate all sub-pages of the
application
–
Wild cards are allowed
51. Deploying OpenSocial Widgets in Notes and iNotes
51
Approved widgets need to be installed
in Notes and iNotes
Widgets can be pushed to end users
by policy settings
–
This is the recommended way to
deploy widgets
End users can also install additional
widgets from catalog by themselves
55. Using the IBM SBT To Render Gadgets
55
Using some of the OSGi bundles found in the IBM SBT you can not render gadgets within
your own apps
–
You can allow users to integrate into your applications using gadgets
–
You can build a dashboard based on gadgets
–
You can embed the Connections Activity Stream gadget within your application
The OSGi bundles from the SBT provide a service that other apps running on Domino can
use to render their own gadgets
Supports both WABs (Web Application Bundles) and XPages on Domino
–
You can use extension points to contribute “containers” to the OpenSocial service
running on the Domino server
56. Key Concepts
56
Depend on com.ibm.sbt.opensocial.domino or com.ibm.xsp.opensocial
To render gadgets within your own application you must supply at least one instance of a
class that implements ContainerExtPoint
–
Can be registered via the extension point com.ibm.sbt.opensocial.domino.container
●
This should be used by OSGi bundles
–
Can be registered by calling ContainerExtPointManager.registerContainers
●
This should be used by XPage apps
Then you need to include a script tag in your application to include the OpenSocial
Container JS
–
[domino server]/osplayground/gadgets/js/container:embedded-experiences:openviews:actions:selection.js?c=1&debug=1&container=sampleId
–
The container id must match the one from your ContainerExtPoint
58. Security Tokens
A security token is an encrypted string which contains information about the user, container,
and app
It is required in order to render and gadgets in your application
GET /sbtos/container/stgen
Parameter Name
c
The domain of the container
i
The app ID. Any unique ID for your app will do.
m
The module ID, should always be 0.
u
58
The ID of the container.
d
Description
The app url.
Response: {“token” : “123”, “ttl” : 5678}
61. XPages and OpenSocial
61
XPages and Embedded Experience mail
–
XPages can be embedded in mail directly by using a URL embedded experience
–
Gadget XML can be put in an NSF and access application data via XPages REST API
–
It's easy to send embedded experience emails from XPage apps
XPages and Activity Streams
–
Support to post activities with embedded experiences to activity streams
–
Support to read activity stream data in XPages apps
63. XPages Simple Action To Send Embedded Experience
Emails
New “Send Mail” simple action
–
Available in 9.0
–
Provides an easy way to send mails and
supports Embedded Experience mail
–
You can either compose JSON by
yourself or XPages will compose it
based on your input.
–
63
64. Leveraging SSO For XPage Embedded Experiences
We do not want users to log in again when opening a XPage embedded experience
The mail server and the server hosting the XPages app must have multi-server SSO
enabled
–
For iNotes users, the servers must be in same SSO domain
–
For Notes users, a managed account needs to be created for the server hosting the
XPages application
●
This can be pushed via policy
In the case of XPage embedded experiences in the Connections activity stream, the
Connections server must be in the same SSO domain as the Domino server hosting the app
–
If you want to integrate a classic web based Domino application with embedded experience, the
above steps apply as well.
64
67. Resources
67
OpenSocial Tutorials: https://opensocial.atlassian.net/wiki/display/OS/Home
OpenSocial Explorer: http://opensocial.github.io/explorer/download.html
Apache Shindig: http://shindig.apache.org
IBM Social Business SDK: http://ibmsbt.openntf.org/
IBM Social Business Toolkit Playground:
https://greenhouse.lotus.com/sbt/SBTPlayground.nsf/
IBM Domino 9.0 Social Edition OpenSocial Component Deployment Cookbook:
http://www-10.lotus.com/ldd/dominowiki.nsf/dx/IBM_Domino_9.0_Social_Edition_OpenSocial_D
Developing Gadgets For Connections:
https://www.ibm.com/developerworks/lotus/documentation/osgadgetconnections4/index.html
OpenSocial Specs: https://opensocial.atlassian.net/wiki/display/OSD/Specs
OAuth Client Registration:
http://www-10.lotus.com/ldd/lcwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+4.0+d
Activity Streams API:
http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Connections+
68. Resources
68
OpenSocial Gadgets In The Playground:
https://github.com/OpenNTF/SocialSDK/wiki/OpenSocial-Gadgets-In-The-Playground
Building OpenSocial Containers Using The SBT:
https://github.com/OpenNTF/SocialSDK/wiki/Building-Your-Own-OpenSocial-Container
70. Engage Online
SocialBiz User Group socialbizug.org
– Join the epicenter of Notes and Collaboration user groups
Follow us on Twitter
Engage
– @IBMConnect and @IBMSocialBiz
Online
LinkedIn http://bit.ly/SBComm
– Participate in the IBM Social Business group on LinkedIn:
Facebook https://www.facebook.com/IBMSocialBiz
– Like IBM Social Business on Facebook
Social Business Insights blog ibm.com/blogs/socialbusiness
– Read and engage with our bloggers
70
71. Access Connect Online to complete your session surveys using any:
– Web or mobile browser
– Connect Online kiosk onsite
71