ibm connections iwidget development
DESCRIPTION
This presentation goes into detail how you can embed 3rd party applications into IBM Connections using iWidgets. Topics include: iWidget overview, Deployment & Configuration, APIs, and authentication optionsTRANSCRIPT
© 2014 IBM Corporation
iWidget DevelopmentIBM Connections 5.0 Workshop
Author: Paul GodbyIBM Ecosystem DevelopmentDuration: 45 minutes
Agenda
● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication
Overview
● Definition, according to the iWidget 1.0 specification:● “A browser-oriented component, potentially extending a server-side component,
that provides either a logical service to the page or a visualization for the user (normally related to a server-side component or a configured data source).”
● An iWidget is a basic building block for adding new features to IBM Connections● Use iWidgets to socialize and integrate your applications into IBM Connections● Custom iWidgets can be added to: Home Page, Profiles, and Communities● Comprised of the following components
● XML widget descriptor● JavaScript files (optional)● CSS files (optional)
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.0
● 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
Agenda
● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication
XML widget descriptor
● Placed on any HTTP server
Tag Attribute Description
iw:iwidget id Unique identifier
supportedModes View modes supported by the widget
mode Default view mode to use
iScope Name of the JavaScript instance
iw:resource uri Links to additional JavaScript or CSS files
iw:content mode Default HTML to use when a view is loaded
Resource bundle
● A .properties file that defines UI strings for the application● Create a text file and give it a name unique to your application
● Example: com.ibm.idr.exercise1.properties● Place the file in the “strings” folder of the shared customization directory● Add key / value string pairs for the widget title and description
● Overrides the default values generated by the iWidget framework● Add additional key / value string pairs as appropriate for the application
LotusConnections-config.xml
Tag Attribute Description
widgetBundle name ● Name of the resource bundle containing your strings
● Corresponds to the name of the file placed in the strings customization directory
prefix ● Unique ID of the bundle in Connections● Used for later references to the bundle
● Define any custom resource bundles used
widgets-config.xml
Tag Attribute Description
widgetDef defId ● Unique identifer● The key in the properties file for the title
description The key in the properties file for the widget palette description
bundleRefId ● Name of resource bundle to load● Bundle was defined in LotusConnections-config.xml
url Location of the XML descriptor for the iWidget
itemSet item name Name for a predefined attribute
value Value for the predefined attribute
● Inform IBM Connections about the widget and where to find it● Provide configuration information in the form of ItemSets
Putting all of the components together
Agenda
● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication
Common iWidget deployment tasks
● Optional tasks● Create a resource bundle
– Contains UI strings such as the title, description, labels, etc.
● Register the resource bundle in IBM Connections (required, if using bundles)– Tell Connections to load the bundle and where to find it
● Configure the AJAX Proxy– Only required if the widget makes AJAX requests to other servers/ports
● Required tasks● Create the widget XML descriptor file
– Contains details about your widget, including pointers to additional resources to load
Configure the AJAX proxy
● If your application will make AJAX requests to other servers...
● Navigate to the “LotusConnections-config” directory
● Make a copy of proxy-config.tpl and rename it according to the IBM Connections application that will contain the widget
● Using wsadmin, check out/in the proxy-<app>-config.tpl file
● Add a new proxy rule for the HTTP server that will be hosting the iWidget
Home Page iWidget deployment
1) Declare Home Page administrator(s)
2) Home Page administrators can:● add/remove widgets● enable/disable widgets
3) End users can then customize their Home Page from the widget palette
Add/Remove Home Page widgets
● Use the Home Page administration UI to add/remove widgets
Enable/Disable Home Page widgets
iWidgets in the Home Page
Communities iWidget deployment
● In addition to the common tasks, register the widget in IBM Connections● Tell Connections about your widget and where to find the XML descriptor● Widget will appear in the widget palette (unless showInPalette=”false”)
● Optionally can configure mandated widgets● Define the UI location for the widget in the “layout” section of widgets-config.xml
Tag Attribute Description
widgetInstance uiLocation Defines the location of the widget on the page.Possible values: col1, col2, col3
defIdRef The widget definition to which this instance is bound.Maps to the “defId” attribute in the widget definition.
iWidgets in Communities
Profiles iWidget deployment
● In addition to the common tasks, register the widget in IBM Connections● Tell Connections about your widget and where to find the XML descriptor
● Define the UI location for the widget in the “layout” section of widgets-config.xml
Tag Attribute Description
widgetInstance uiLocation Defines the location of the widget on the page.Possible values: col1, col2, col3, or tabsWidget1
defIdRef The widget definition to which this instance is bound.Maps to the “defId” attribute in the widget definition.
iWidgets in Profiles
Agenda
● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication
iScope
● Defines the name of the instance of the JavaScript class● The class written by the widget developer that contains the widget logic
Lines Description
1 Tells Dojo a module has been provided with the given name (the iScope)
2 Dojo class declaration
4 Called once when class is instantiated
7 Called when iWidget is loaded
10 Called when iWidget mode is “view
13 Called when iWidget mode is “edit”
iContext
● An iContext instance is automatically provided for the iScope class● Used to interact with the iWidget framework● Provides access to
● DOM● I/O functions● Widget attributes● User attributes
● Important functions:● iContext.getRootElement()● iContext.getElementById()● iContext.getiWidgetAttributes()● iContext.getUserProfile()● iContext.io.rewriteURI()● iContext.iEvents.fireEvent()
ItemSet
● A data abstraction in the form of key / value string pairs● Provide the widget with information about the embedding environment● Can be declared in the widget preferences● Can be retrieved using the iContext object and function: getItemValue(“key”)
Widget preferences
● Default widget attributes can be specified in widgets-config.xml● <widgetDef> → <itemSet> → <item>
User Profile
● A predefined itemSet containing information about the authenticated user● Returns “null” if user is not logged in (Profiles and Communities allow anonymous)
● displayName = display name● email = e-mail address● userid = the IBM Connections unique user ID
Using the persistent data store
● Persist data on a per widget basis across sessions
● Tip!● If you need to store a lot of data, consider consolidating the data in a single JSON
object, then write the serialized string to the store● Quickly store / retrieve information with a single API operation and improve
responsiveness by minimizing HTTP requests
Making AJAX requests
● Dojo provides cross-browser XHR functions for making AJAX requests● dojo.xhrGet, dojo.xhrPost, dojo.xhrDelete, dojo.xhrPut
io.rewriteURI
● Modern browsers have a “Same Origin Policy” in place to prevent cross-site scripting (XSS) attacks
● JavaScript can only make AJAX calls to the originating server● To get around this problem, IBM Connections has an AJAX Proxy● If your application makes AJAX requests to different servers (or ports), you must
rewrite URLs so that they are processed by the proxy
Making AJAX requests using the Proxy
● Updated code with rewritten URL for the AJAX Proxy● An asynchronous callback (such as an AJAX request) can lose track of it's scope
● Use dojo.hitch to force a function to use the provided scope
IBM Connections REST API
● A REST API is available that allows you to perform most functions that are possible with the default web UI
● The API for each Connections application is fully documented in the official wiki● Uses AtomPub standard and HTTP CRUD operations for working with content
● These HTTP requests may not need to be proxied depending on your environment!● Only an issue if features reside on separate servers
Accessing IBM Connections features
● Due to different deployment configurations, the URL of a particular IBM Connections feature might not be known during widget development
● You can insert the root URL of IBM Connections features using ItemSets
Component Variable
Activities activitiesSvcRef
Blogs blogsSvcRef
Bookmarks dogearSvcRef
Communities communitiesSvcRef
Profiles profilesSvcRef
Retrieve Feeds using the REST API
Create new entries using the REST API
*** Line 25: You MUST set this header or IBM Connections will reject the API request!
Use an iFrame
● Quickly develop a POC or demo using iFrames to display external sites or pages
Agenda
● Overview● Components of an iWidget● Deployment / Configuration● APIs● Authentication
Authentication Options
● Single Sign-on (SSO)● IBM session cookies = LtpaToken or LtpaToken2
– Can be used between WebSphere and Domino environments
● If your back-end server is not WebSphere or Domino based...– Can use 3rd party products to integrate IBM and non-IBM servers
● Tivoli Acess Manager, SiteMinder, etc.
– Can generate own trusted cookies using a combination of the current user's ID and some unique keys entered in widgets-config.xml
● Basic● Provide a Base 64 encoded username / password pair with each request● Can store the credentials in the iWidget persistent store
● OAuth● Login provided by a 3rd party provider● User authorizes application to access resources for a given time period
Thanks!
● Access FREE education on the IBM Collaboration Solutions portfolio of products today!
1. Visit the IBM Greenhouse and create a free account.
Link → http://greenhouse.lotus.com/
2. Visit the IBM Collaboration Solutions Ecosystem Development Community
Link → https://greenhouse.lotus.com/communities/community/icsecod
3. Learn new skills and share these links with your friends and colleagues!