bp205: there’s an api for that! why and how to build on the ibm connections platform

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 AS A PLATFORM

IBM Connections as a PLATFORM

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.addApplication("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 in Profiles

Widgets in Communities

Widgets - modes

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>


<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


<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 – 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

THE ACTIVITY STREAM

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”: ”[email protected]”, ”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)

THE SPI’S

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 configured using events-‐config.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!

bp205: there’s an api for that! why and how to build on the ibm connections platform

Software

ibm connections ibm

ibm notes

views of ibm

nonibm products

customers business

legal advice

legal requirements

services available