OpenSocial is a community standard managed by the OpenSocial foundation. Several major companies (Google, IBM, SAP, Atlassian ...) are involved in the OpenSocial standard.
You can consult the full OpenSocial specification here, but at a glance OpenSocial scope includes :
The idea is similar to the JSR 168 portlet with some differences :
- rendering is mainly done on the client side (Browser side)
- OpenSocial gadgets are independant of the server side technology (Java, Php, Python, .Net ...)
- deploying a new gadget is simply referencing a URL that contains the XML gadget spec
OpenSocial defines a set of Rest WebServices that must be implemented by compliant container.
The main services are:
- App Data service : service to store user specfic data for each gadget / app
- Groups service : manage relationship between users. (each user has the ability to manage his own groups : friends, coworkers, ...)
- Activity service : track user activity
- Person service : standard access to the users of the system
- Message service : simple messaging system
These web services provide the "social part" of the OpenSocial technology.
Manage authentication and security of data accesses
In OpenSocial there are usually 3 actors:
- the user : the human looking at the gadget inside his browser
- the container : the "server" providing the container page where the gadgets are rendered
- the service provider : the server providing the Rest service accessed by the Gadget
Additionally, the AppId (i.e. the gadget) may be taken into account.
Also, OpenSocial differentiate 2 types of user identify:
- the viewer : the user in front of the browser
- the owner : the user owning the page that contains the gadget
If you take the example of a gadget that display inside Nuxeo your emails from GMail :
- you are the user (OpenSocial viewer and OpenSocial owner)
- Nuxeo is the container
- GMail is the service provider
- the GMail gadget is the AppId
So, the container (here Nuxeo) will manage REST call proxying :
- handling caching if needed
- handling security
The security part is not trivial because in OpenSocial contexte there are 3 constraints :
- you need to delegate authentication to a server
(i.e. let Nuxeo connect to GMail on behalf of me)
- your GMail and Nuxeo account may be completely unrelated
(not the same login for example)
- you may not want to let Nuxeo access all your GMail data, but only a subset
In order to manage theses requirements OpenSocial relies on OAuth.
Nuxeo EP server can be used both as an OAuth Service consumer or as an OAuth Service provider.
You can find more details about OAuth and it's integration in Nuxeo later in this page.
What can it be used for
Dashboard / Portal use case
The most direct use cases is to use OpenSocial gadgets to adress Dashboard / Portal use case.
This is currently the default usage of OpenSocial within Nuxeo CAP / DM.
For that, we have created some simple and extensible gadgets :
- My recent documents
- My Workspaces
- My Tasks
The user can then use the Nuxeo's dashboard to have a quick overview of it's activity inside Nuxeo platform.
Using OpenSocial gadgets to do so is interesting because :
Let users control their Dashboards.
Depending on the security policy, the user is able to customize it's dashboard
- add / remove gadgets
- change gadgets configurations
Leverage an open standard
Gadgets can come from several différent services providers
- My Tasks on Nuxeo
- My Task on Jira
- My Google calendar events
More and more application are supporting OpenSocial:
- Google Apps
(also provides an OpenSocial container in GMail and iGoogle)
- Atlassian Jira and Confluence
(that are also OpenSocial container)
- Social Oriented services like LinkedIn, MySpace, Hi5, Orkut ...
So you can add external gadgets to Nuxeo's Dashboard, but you can also use an external OpenSocial Dashboard provided by an other application and use Nuxeo's gadgets from inside this container.
Manage user identity
Because OpenSocial relies on OAuth you can have a narrow controle of what service may be used and what scope of data you accept to share between the applications.
Deploying an OpenSocial gadget in a container is as simple as giving a new Url.
Easy contextual information integration
OpenSocial gadgets can also be used to provide a simple and light integration solution between 2 applications.
For exaample, you can :
- display some informations comming from SAP next to the Invoice Document in Nuxeo
- diplay links to related Nuxeo Documents from within a confluence wiki page
- display specification documents (Stored in Nuxeo) from withing the Jira Issue
An more generally, if you have Enterprise wide Rest WebService (like Contacts managements, Calendar management ...) you can expose them via OpenSocial gadgets so that theses services are accessible to users of all OpenSocial aware applications.
Social network management
Because OpenSocial standardize a set of Social oriented services, you can easily leverage the data from all OpenSocial aware applications.
For example you can have an aggregated view on the activity stream.
In the context of Document Management, Collaboration and KM, Social APIs really makes sense :
- manage communities
- manage activity
- manage user skils
OAuth in Nuxeo EP
Starting with 5.4.1, Nuxeo EP provides full support for OAuth.
Nuxeo as a service provider
You may want to use Nuxeo as an OAuth Service provider :
- if you have an OpenSocial gadget that uses a REST service from Nuxeo
- if you have a external application that uses a REST service from Nuxeo
Unless the service consumer is a gadget directly hosted inside Nuxeo, you will need to do some configuration at Nuxeo's level to define how you want the external consumer to have access to Nuxeo.
Nuxeo as a service consumer
If you need to access an external REST service from within Nuxeo, you may want to use OAuth to manage the authentication.
If you use this external service from within an OpenSocial gadget, you will need to use OAuth.
Unless the service you want to consumer is hosted by your Nuxeo instance, you will need to do some configuration do define how Nuxeo must access this external service.
For more details about OAuth support in Nuxeo, please see the dedicated section.
Nuxeo Automation REST services
OpenSocial gadgets typically use REST services to fetch the data from the service provider.
When Nuxeo is the service provider, the recommended target API is Nuxeo Automation :
- provide a solution to easily have custom REST Apis without having to write code
(Using Nuxeo Studio)
- common access point for all REST services
(All Operation and Chains can be called the same way)
- native support for JSON marshaling
(means easy integration in the Gadget JS)
- built-in samples in Nuxeo Gadget
If you have already built custom automation chains to expose a high level API on top of Nuxeo, you can easily expose theses services via an OpenSocial gadget.
Gadgets in Nuxeo EP
Apache Shindig, GWT and WebEngine
OpenSocial integration in Nuxeo is based on Apache Shindig project.
Nuxeo OpenSocial modules were originally contributed by Leroy Merlin and includes :
- Shindig integration
- a WebEngine based Gadget spec webapp ( /nuxeo/site/gadgets/ )
- a GWT based gadget container
- a service to contribute new gadgets
Gadget spec generation
Gadget Spec is the XML file defining the Gadget.
It's a static XML file that :
- describes the gadget
- list the required features of the gadget
- contains the translation resources
- contains the authentication informations
Inside Nuxeo, the Gadget Spec is dynamically generated from a FreeMarker template using WebEngine.
Using WebEngine and Freemarker to generate the spec add more flexibility and power :
Most of you gadgets will share some common content.
In order to avoid that issue, when writing a gadget spec in Nuxeo, you can use Freemarker includes that will be resolved :
- locally to the gadget directory
- globally in the webengine-gadget bundle (in skin/resources/ftl)
The same logic applies for JS et CSS resources that will be resolved :
- locally to the gadget directory
- in the gadget bundle
- globally in the webengine-gaget bundle (in skin/resources/scripts or skin/resources/css)
Better context management
When generating the GadgetSpec you need to take into account several parameters :
- urls : resources URLs may be dependent of your config
- Nuxeo host name may change
- some resources are accessed from the client side (from the browser)
- some resources are accessed from the server side (Server to Server communication)
- Authentication : depending on the target Host of the gadget authentication config may change
- you want to use 2 Legged integrated authentication when gadget is inside Nuxeo
- you want to use 3 Legged authentication when gadget is hosted inside an external application
In order to address these problem the Freemarker template is rendered against the fellowing context :
gives access to the InternalGadgetDescriptor object
Server side url used to access the Nuxeo server
Client side url used to access the Nuxeo server
Context path of the Nuxeo WebApp (i.e. nuxeo)
Boolean flag used to tell if gadget will be renderd inside Nuxeo or in an external application
Access to a Java Helper class to manage i18n (see later)
base URL for accessing the gadget virtual directory
Access to a Java Helper class to manage the "Nuxeo context" of the gadget if needed : Repository name, domain path ...
The inside flag is "automatically" determined by Nuxeo, but in case the consumer application and Nuxeo are on the same host (i.e. communication via locahost or 127.0.0.1), you may force the external mode by adding external=true to the gadget spec url :
All request parameters you may pass in the gadgetSpec url will also be available at the root of the freemarker context.
GadgetSpec needs to provide XML files for all translations.
So, of course you can use static resources for these translation files.
The main problem is that in this case you can not leverage the existing translations in Nuxeo and it's hard to contribute new translations.
In order to avoid that, Nuxeo proposes a dynamic translation mode, where messages files are dynamically generated based on the standard messages files used in the JSF webapp.
To activate the dynamic i18n features you need :
- to provide a dynamic_messages.properties file that will list the needed label codes and associated default values
- use the include that will automatically generate the needed translation files and associated entries in the XML Spec
Dynamic management of Authentication
As explained earlier, depending of the target context, the Spec needs to define OAuth 3 legged or 2 Legged.
You can do it by hand, or you can use the oauth include :
In order to make Gadget creation easier, Nuxeo provides some building blocks for common features :
- Context management
- Automation REST calls
- Documents list display
Thanks to these building blocks, writing a full featured gadgets base on Automation API is very simple.