IBM Connections API for building apps

BP205: There’s an API for
that! Why and how to build
on the IBM Connections
PLATFORM
Mikkel Flindt Heisterberg
Senior Solution Architect and Partner
OnTime®

About me
§  Developer, geek, father
§  With IntraVision the makers of OnTime® Group
Calendar – we are in the TechnOasis
§  Love developing plugins for IBM® Notes® and
developing for IBM® Connections®
§  IBM® Champion since program inception
§  Twitter: @lekkim
§  Blog: http://lekkimworld.com

Notices and Disclaimers
Copyright © 2015 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission from IBM.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM.
Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of initial publication and could include
unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED.
IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF
PROFIT OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided.
Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice.
Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers have used IBM products and the results
they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary.
References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business.
Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials and discussions are provided for informational
purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation.
It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulatory
requirements that may affect the customer’s business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or represent or warrant that its services or products
will ensure that the customer is in compliance with any law.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products in connection with
this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers
of those products. IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES,
EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The provision of the information contained herein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other intellectual property right.
IBM, the IBM logo, ibm.com, BrassRing®, Connections™, Domino®, Global Business Services®, Global Technology Services®, SmartCloud®, Social Business®, Kenexa®, Notes®, PartnerWorld®, Prove It!®,
PureSystems®, Sametime®, Verse™, Watson™, WebSphere®, Worklight®, are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service
names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at: www.ibm.com/legal/copytrade.shtml.

Agenda
§ Introduction to
– IBM Connections as a PLATFORM
– The API’s - REST’o’RAMA
– Widgets for IBM Connections
– Developing for the Activity Stream
– The SPI’s specifically the Event SPI
§ Demo and demo application

IBM Connections == series of services and building blocks

THE API’S –
REST’O’RAMA
Fire up your REST client and get crackin’!

All features have an API
§  All API’s are based on Atom standard – pretty verbose using XML for
output but once you grok it it’s pretty easy to go between features.
§  Please use API’s where ever possible and refrain from going directly to the
backend databases although it’s possible…
§  All API’s support basic and form based authentication (LptaToken(2)) as
well as OAuth. Some API’s allow anonymous access as well.
§  For server side applications I suggest you use OAuth where possible as
issuing requests on users behalf isn’t feasible using form based or basic
authentication.

OAuth 2.0
§  OAuth 2.0 allows an application to work on a users behalf after the user grants this
authority to the application.
§  Application requests OAuth support from IBM Connections and the user authorizes
the application using two URL endpoints. The user can revoke the authorization at
any point.
§  Please do not bother with OAuth if integration (API usage) is
done on the glass i.e. from a browser application such as a
widget. OAuth should only be used if a server side application
needs to work on behalf of the user (and LtpaToken(2) access
cannot be guaranteed).

OAuth 2.0 – register application using wsadmin
wsadmin>import sys
wsadmin>execfile("oauthAdmin.py”)
wsadmin>OAuthApplicationRegistrationService.addApplicati
on("bp205", "BP205 Demo",
https://inside.intravision.dk/bp205/oauth20_cb)
An application was added with the new id bp205.
wsadmin>clientSecret =
OAuthApplicationRegistrationService.getApplicationById
("bp205").get("client_secret”)
wsadmin>print clientSecret
MSGxGCQhGUcM93n50CalSk1Du1svohfy3SattAqhRDQcm...

The appplication development wiki is your friend

WIDGETS
Psssst!! They are actually iWidgets… And then there are gadgets but
that’s something else…

Widgets - modes
§ There are 4 modes defined
– View
– Fullpage
– Search
(only for Communities)
– Edit

Widgets – descriptor
<iw:iwidget id="com.example.MyWidget" supportedModes="view fullpage”
mode="view” lang="en" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
iScope="com.example.MyWidget">
<iw:resource uri="http://www.example.com/widget1/MyWidget.js" />
<iw:resource uri=”./MyWidget.css" />
<iw:content mode="view">
Loading...
</iw:content>
<iw:content mode="fullpage">
<![CDATA[
<div id="_IWID_widgetContent">Loading...</div>
]]>
</iw:content>
</iw:iwidget>

Widgets – descriptor
<iw:iwidget id="com.example.MyWidget" supportedModes="view fullpage”
mode="view” lang="en" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
iScope="com.example.MyWidget">
<iw:resource uri="http://www.example.com/widget1/MyWidget.js" />
<iw:resource uri=”./MyWidget.css" />
<iw:content mode="view">
Loading...
</iw:content>
<iw:content mode="fullpage">
<![CDATA[
<div id="_IWID_widgetContent">Loading...</div>
]]>
</iw:content>
</iw:iwidget> _IWID_ replaced at runtime with the widget ID
(iContext.widgetId) – very nice if you want to allow multiple
instances of your widget on the same page

Widgets – iScope – declaration using dojo
dojo.provide("com.example.MyWidget");
dojo.declare("com.example.MyWidget", null, {
constructor: function() {},
onLoad: function() {},
onView: function() {},
onEdit: function() {},
onFullpage: function() {},
onSearch: function() {}
});

Widgets – iScope – declaration using vanilla JavaScript
// define namespace (not best of breed code)
if (!window[”com”]) window[”com”] = {};
if (!window.com[”example”]) window.com[”example”] = {};
// define constructor and methods in prototype
window.com.example.MyWidget = function() {
// constructor
}
window.com.example.MyWidget.protototype.onLoad = function() {
// onLoad method
}
window.com.example.MyWidget.protototype.onView = function() {
// onView method
}

Widgets – adding to the UI
Declaratively configured using widgets-config.xml

<widgetDef defId="com.example.MyWidget”
url="/widget1/MyWidget.xml" loginRequired="true”
showInPallette=”true” primaryWidget=”false”>
<itemSet>
<item name="profilesCtx" value="{profilesSvcRef}" />
<item name="myProp" value="Abc123" />
</itemSet>
</widgetDef>

Widgets – iContext
§  An iContext instance is set into the iScope instance
§  The iContext provides access to the widget markup (e.g. root element),
I/O related functions (i.e. URL rewriting), widget attributes etc.
§  The iContext is easily accessed from the iScope class using
this.iContext
§  Important
func-ons
include:
–  iContext.getRootElement() : DOM Element
–  iContext.getElementById(id:string) : DOM Element
–  iContext.getiWidgetAttributes() : ItemSet
–  iContext.getUserProfile() : ItemSet
–  iContext.io.rewriteURI(uri:string) : string
–  iContext.iEvents.fireEvent(name:string, type:string,
payload:object)

WIDGETS AND
LOADING
IBM Connections v.5 changed a lot and not necessarily for the better…

IBM Connections v.5 changed a lot
§  Prior to IBM Connections v.5 the browser loaded the resources for widgets hence the
resources were cached by the browser.
–  Browser cache is easy to clear and updated resources (JavaScript / CSS) could be loaded easily.
§  From IBM Connections v.5 the Common module aggregates and caches all widget
resources making it near impossible to work with for development.
§  Still no appdev environment for iWidgets.
§  Suggest using a mock environment approach loaded through the AJAX proxy of IBM
Connections. This allows easy development with tons of pains and frustration from having
to battle the Common module and having to restart servers and applications.
§  Will show example later…

Loading prior to IBM Connections 5

Loading from IBM Connections 5

Loading from IBM Connections 5
http://www.youtube.com/
watch?v=1GLpA604Iic

Activity Stream
§ The following is based on my
highly acclaimed (cough,
cough) presentation on the
Activity Stream
§ Much more detail and many
more examples there
§ See http://slideshare.net/lekkim
for complete presentation

Activity Stream
§ IS
– River of news – it’s like water flowing by you
– Notifications about ”stuff” happening in (other) systems – we refer to
these notifications as entries
§ ISN’T
– A new inbox – doesn’t replace email
– A perpeptual data store – entries are deleted based on a server
defined purge interval (default is 30 days) unless saved or actionable

Activity Stream
§ In my opinion it makes most sense to not consider the
activity stream as one single stream
§ Instead think that
– Each user has his/her own (@me)
– There is a public stream (@public)
– A community may have a stream if the widget has been added
by a community owner – if there’s no stream for a community
posting to it will return a ”403 Forbidden”

Activity Stream
•  You will mainly use the POST and PUT methods to send JSON data (Content-Type: application/json) to
the API
•  JSON is super simple key/value data format. It has simple datatypes (strings, numbers, booleans),
objects and arrays
{
”email”: ”mh@intravision.dk”,
”niceGuy”: true,
”age”: 38,
”name”: {
”first”: ”Mikkel Flindt”, ”last”: ” Heisterberg”
},
”Connectospheres”: [6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
}

Activity Stream – minimum POST body
{
"actor": {"id": "@me"},
"verb": "post",
"title": "Some entry title",
"updated": "2013-05-17T12:00:00.000Z",
"object": {
"title": "Some object title",
"objectType": "note",
"id": "1234567890-1234567890-1234567890"
}
}

Activity Stream – building the URL
https://<host>/connections/opensocial/<auth>/rest/activitystreams
/<user ID>/<group ID>/<application ID>/<activity ID>
Component Meaning
<auth> (optional) If using form based authentication leave this component out. Otherwise options are anonymos, basic,
oauth.
<user ID> The user whose stream you’re addressing – use @me for current users stream, @public for public stream or a
community ID for the stream in a community.
<group ID> The group of entries you’re addressing – use @all for all posts or options for special meaning such as @saved,
@actions, @mentions. Refer for InfoCenter and resources slide for more.
<application ID> When retrieving entries this refers to the application (or ”generator”) that created the entry. All the IBM Connections
app names can be used (profiles, blogs, wikis etc.) plus custom ones (e.g. ontimegc). @all used for all
applications.
<activity ID> Used to reference a specific event e.g. for updating saved status.

Activity Stream – URL examples
1.  /activitystreams/@me/@all
List my (current users) entries
2.  /activitystreams/@public/@all
List public stream entries
3.  /activitystreams/@me/@actions
List my actionable events
4.  /activitystreams/@me/@saved/blogs
List my saved events from blogs
5.  /@me/@all/@all/urn:lsid:lconn.ibm.com:activitystreams.story:bdb562f…
Work with entry from my stream based on ID
* All URLs above start with
https://<host>/connections/opensocial/<auth>/rest
Also used
when creating
new entries
(e.g. POSTing)

Other Programming Interfaces
§  SPIs are lower-level programming interfaces which may be subject to modification from
release to release.
§  Event SPI
–  The Event SPI allows third parties to consume event data generated by IBM Connections.
§  Seedlist SPI
–  Use the Seedlist service provider interface (SPI) provided with IBM Connections to integrate your search
engine with IBM Connections content.
§  Service SPI
–  You can use the Service SPI to learn about the applications running in your IBM Connections deployment.
§  User SPI
–  You can use the User SPIs to access information about the users in your IBM Connections deployment.

Event Handlers – declaration
Declara-vely
conﬁgured
using
events-‐conﬁg.xml

<postHandler enabled=”true" invoke="ASYNC"
name=”MyEventHandler” class="com.example.MyEventHandler">
<subscriptions>
<subscription source="*" type="*" eventName="*"/>

</subscriptions>
</postHandler>

Event Handlers – implementation
public class MyEventHandler implements EventHandler {
public void init() throws EventHandlerInitException {}
public void destroy() {}
public void handleEvent(Event event) throws EventHandlerException {
String eventName = event.getName(); // event name
Person actor = event.getActor(); // person that triggered event
// look at the event name
if (event.getName().equals("profiles.person.photo.updated")) {
// a profile photo was updated
this.doEventProfilesPhotoUpdated(event);
} else if (event.getName().equals("profiles.updated")) {
// a profile was updated
this.doEventProfilesUpdated(event);
}
}
}

Event Handlers – summary
§ Make event handlers asynchroneous
§ Be defensive – consider what happens if events are lost
– What happens if your event handler fail?
– What happens if the recipient of the event (3rd party API) fail?
§ Suggestion:
– Do a minimum of processing in the event handler and then post
message with data to a durable queue. Have the queue consumer –
e.g. a message driven bean – do the real processing as it can be
done under transaction control

Demo
§  WebSphere® Application Server Enterprise Application (WAS EAR)
–  BP205_JAR: Shared code
–  BP205_WAR: Web application module – API servlet and widget component
–  BP205_EJB: Enterprise Java Bean modules comprising the business logic components
–  BP205_EAR: Combines the above three into a single installable application
§  IBM Connections Event Handler
–  BP205_EventHandler: Event handler installed into WAS and configured using events-config.xml
§  WebSphere Application Server queue
–  Event handler listens for events, extract data and post message to queue. Messages picked up
by message driven bean (MDB) and passed into busiess logic components

Engage Online
§  SocialBiz User Group socialbizug.org
–  Join the epicenter of Notes and Collaboration user groups
§  Social Business Insights blog ibm.com/blogs/socialbusiness
–  Read and engage with our bloggers
§  Follow us on Twitter
–  @IBMConnect and @IBMSocialBiz
§  LinkedIn http://bit.ly/SBComm
–  Participate in the IBM Social Business group on LinkedIn
§  Facebook https://www.facebook.com/IBMConnected
–  Like IBM Social Business on Facebook

Thank you
§ Presentations on slideshare.net – this one is coming
§ Contact me – often times more than willing to help
§ Questions? Fire away!

IBM Connections API for building apps

Recommended

Recommended

More Related Content

What's hot

What's hot (18)

Viewers also liked

Viewers also liked (10)

Similar to IBM Connections API for building apps

Similar to IBM Connections API for building apps (20)

More from Mikkel Flindt Heisterberg

More from Mikkel Flindt Heisterberg (15)

Recently uploaded

Recently uploaded (20)

IBM Connections API for building apps