Integrate Applications into IBM Connections Cloud and On Premises (AD 1632)

AD-1632Integrate your Application Into IBM Connections Cloud and On-PremisesMichael Gollmick / Felix Binsack / Feb/03/2015

About this session• We share some of our experience gained in the past three

years creating and maintaining a complex application that integrates into and leverages IBM Connections.

• Target Audience are Software Architects and Developers

Agenda• About TIMETOACT & Me• Short Demo• Cloud and On-Premises: One or Two Worlds?• Architectural Questions and Decisions• Integrating your Application• Integration APIs• Customizing the Navigation• Tools and Landscape

About TIMETOACT

• European Business Partner• One of the largest ISVs for IBM Connections Software

Simplify and Improve IBM Connections Administration, Content Management and User Management http://connections-apps.com/cat

Integrate Internal Communications and Custom Applications into IBM Connectionshttp://connections-apps.com/xcc

Self Services and User Management, Password and Security Management for External (Guest) Usershttp://connections-apps.com/uam

About me• Software Architect, Developer and

Consultant• 15+ years IBM Technologies• Focused on Web Applications, IBM

Connections, Notes & Domino• XCC Team since 2012

Brief DEMO of an integrated Application

How does such an Application look?

Cloud and On-Premises:One or Two Worlds?

Creating a Product• XCC is an application that leverages IBM Connections

information to create a modern and social intranet• It shows web content from different sources aggregated into

one or more pages• It even allows development of Custom Apps• It is designed to run on both, Cloud and on-premises• During conception and implementation we faced challenges -

caused by the two different worlds of the Cloud and On-Premises Software base

Develop Once, Deploy to Cloud and On-Prem• Custom apps can be done for either platform• If you develop a product, it is best developed for both• If a company uses the cloud or on-premises a decision is made

of many more factors than only development• Customers may start off on-premises and then switch to the

cloud or vice versa• Currently development cannot be recommended clearly for one

of each - doing both seems to be the right decision• You should be open for both directions

Challenge - One App in Two Worlds• What might look similar are two planets in the same solar

system: On-premises and cloud might look the same but differ

• That leads to challenges for developers: Different or missing APIs Cross Domain Requests in the cloud Authentication UI Integration, Navigation Bar

• Good News: a lot is similar or close

Two Worlds - One Source Code – Why?• Makes development more effective• Allows for more flexibility• It just makes sense to reuse your code in both worlds• Use parts exclusively and other parts shared in both worlds• Takes some extra effort to be done but is worth the time• Pushes performance to the max

if performance is not urging, more abstraction could make the job even easier

Architectural Questions and Decisions

Architectural Questions I• What application stack to use?

Application Stack is your choice Java is best supported here

• Use one or more resource locators / servlets? More locators allow for better modularity, control

• What persistence technology to use? Cookies, Localstorage in Client Filestorage or Database in Server? What database?

Architectural Questions II• What browsers to support?

Companies seem to love ancient Internet Explorers, users and developers like others better

The more browsers you support the more robust your code gets

• What JavaScript Framework to use? Use Dojo or something else?

• What CSS Framework to use? OneUI, Custom, Bootstrap, others?

Architectural Questions III• Whether to run on-premises, Cloud or both?• How to integrate into the User Experience

Create a Widget, Gadget or Page? Open a completely new UI? Integrate into Navigation?

• What other frameworks to use? Depends on the applications abilities

• What APIs and calls to use?

Architectural Decisions I• With our product XCC we went the following way:

Java/WebSphere Stack Multiple Servlets Localstorage for some client data DBMS for application data

• Database access encapsulated to support more than one DBMS Browser support equivalent to IBM Connections jQuery favored over Dojo (http://xpag.es/?2132) Bootstrap + Custom CSS for a fancy UI (http://xpag.es/?212E)

Architectural Decisions II App runs on both: on-premises and cloud Custom page for App, iWidgets for Communities and Top

Navigation integration Navbar and start page customization for full integration Several more frameworks used:

• IBM Social Business Toolkit (http://xpag.es/?2122)

• OpenJPA (http://xpag.es/?2126)

• JSOUP (http://xpag.es/?212A)

Using solely documented APIs

Application On-Premises Architecture

Connections ServicesBlogs

Comunities

Files

Wikis

Profiles

Bookmarks

Activities

Forums

Search

Activity Stream

Boards

...

XCCPages

Personalization

File Upload

Layout

Grids

Access Rights

Widgets

XCC4Comm

Anonymous

Localization

Flyout

Mobile

Clie

ntJ2

EE C

onta

iner

Stor

age

CNXDB

XCCDB

REST

API

Browser

Application Cloud Architecture

Connections ServicesBlogs

Comunities

Files

Wikis

Profiles

Bookmarks

Activities

Forums

Search

Activity Stream

Boards

...

XCCCloud

Personalization

File Upload

Layout

Grids

Access Rights

Widgets

Mobile

Localization

Clie

ntIB

M C

loud

XCCDB

REST

API

J2EE

Con

tain

er

IBM

SBT

Stor

age

Stor

age

CNXDB

Browser

Integrating your Application

Integration into IBM WebSphere On-Premises• Requires you to create a Java App• Run application on its own server

easier to manage separated logs / troubleshooting

• There is no such thing as a defined Extension page Only workaround is using a “Layout Inheritance”

On-Premises Layout Inheritance I• Good way to do it is:

Pull a page from Connections Parse and modify that HTML to your needs De-Serialize it to the requesting client

• Page to pull: search page (http://xpag.es/?20FE) “About” page might work as well users homepage may help with Activity Stream

On-premises Layout Inheritance II • Advantage:

you are free to do what you like Robust, often even future proof

• works for CNX 4.0 to 5.5 without problems

• Disadvantage: There is no common module/framework

for that, you have to code manually,JSOUP is very helpful

Requires extensive testing in the beginning

Note to IBM:

Please create the same capabilities to retrieve Header and footer for on-premises and cloud

Integration into IBM Bluemix and Cloud• Run WebSphere Liberty Service with your Java App

Liberty is good enough

• Use IBM Social Business Toolkit to Connect• Use OAuth2 to Authenticate• “Inheriting” a page does not work here, build your own page• Integrate Connections Cloud banner (aka Navigation Bar) (

http://xpag.es/?20FA)• Change the Connections Cloud Banner to include your

Application + Hide the „Back To“-Link (more on that later)

Integration APIs

Examples• What can be done with APIs in your application?

Show and vote IdeationsAggregate Calendars of your followed communities into one

REST APIs• Interaction with Connections is RESTful most of the time• Connections APIs have an extensive documentation

API Documentation: http://xpag.es/?211A API Explorer: http://xpag.es/?2112

• You better do not use anything but documented APIs If you find a functionality usable, Open a PMR and ask if that

REST method is supported

• Take care for Internet Explorer Not all versions of that browser are supported for the REST API

The IBM Social Business Toolkit• The IBM Social Business Toolkit (SBT) encapsulates REST API

Requests thru a serverside proxy• That solves the issue with Cross Domain Requests from

JavaScript when interacting with the cloud• SBT handles Authentication

Requests are performed on the users behalf

• Application needs to be registered in your Cloud Organization• Meaningful for accessing application external hosts

Performance penalty if used locally

Customizing the Navigation

Customizing Navigation On-Premises• That‘s a well documented approach (http://xpag.es/?210E)• However, you have to get experience in it• Seamlessly integrates with the „Layout Inheritance“ approach

Customizing Nav in the Cloud• Customization options are limited:

You cannot rename Entries You cannot localize Entries You cannot reorder entries or menus

• But you can: add entries or menus hide or remove entries or menus

• We will show how adding an entry works

Adding a custom Link to your Navigation• Editing the IBM Connections Cloud Navigation is possible but

not that easy• We will cover how to add one such link and how to place it• You will need Organizations Administrative rights• Be warned: a wrong extension modificator string may result in

the loss of the entire Top Navigation• But the result will change the look from this:

• Into this:

Adding a custom Link to your Navigation (II)• Open the Administration Panel (via Admin/Manage

Organization)• Navigate to the „Organization Extensions“• Click „Add Extensions“ button• For field „Service“ use „Top Navigation bar“• Ignore the field „Extension Point“• Leave field „Name“ empty for now – we come to that soon• Field „Description“ is used only in the „Organization

Extensions“ overview, enter description accordingly

Adding a custom Link to your Navigation (III)• Ignore the field „Type“• Enter „https://www“ for the fields „Icon URL“ and „URL“, just to

make the fields validate, their values are totally irrelevant• For the “Name” field we now need to create a magic string• It all starts with „@@mod@“• Then we point to a Top Navigation Bar element with a string

denominating column and element from the following table

Top Navigation ElementsSelector String Target Elementauth-left. myPartnerPage Organization name, displayed next to the brand image

lotusBannerHomepage Home link

networkMenu People menu link

communitiesMenu Communities Menu link

servicesMenu Apps Menu

dashboard-handler Back to IBM Connections Cloud link

myPartnerPage My Organization link

auth-right. bss-adminMenu Admin Menu

chatMenu Chat Menu in the Admin Area

bss-usersMenu User Account Menu

bsscom-helpMenu Help Menu

Adding a custom Link to your Navigation (IV)• Now define the position you want to see the link related to the

targeted node. This could be “@before” or “@after”.• That all is followed by an “@” and a serialized JSON Object:• { "url": "https://www.timetoact.de/xcc", "text": "Intranet"}

• No newlines and special characters and no additional properties allowed!

• Don‘t forget to enable and save the extension

Adding a custom Link to your Navigation (V)• Example: add a new Link right before the Home link in the Top

Navigation bar• That means:

Magic String + Element Selector + Position + JSON @@mod@auth-left.lotusBannerHomepage@before@{

"url": "https://connections-apps.com/xcc", "text": "Intranet"}

• Et voilà:

Removing an Entry from your Navigation• Appears to be as easier than adding an entry• Magic String + Element Selector + delete command

@@mod@auth-left.myPartnerPage@delete@• Will effectively remove the “My Orgnanization” link

@@mod@auth-left.dashboard-handler@delete@• Will effectively remove the “Back To…” link

• Combining all the Extensions mentioned before, creates this Navigation:

Wrap Up Cloud Top Nav Customization• Adding and removing is possible• There‘s more possible:

E.g. Drop Down Menus see http://xpag.es/?2106, http://xpag.es/?210A

• There‘s even more stuff posted to that topic• There are blog entries suggesting this technique is

unsupported – however this seems to be the only way

Tools and Landscape

Recommended Tools I• Just a few random Tools that work very well here:

Eclipse IDE, Notepad++, Sublime, Atom Rational Team Concert

• Source control, if you are seriously developing Maven – mighty but difficult

• Manages application Build Process

• Used in Eclipse Grunt.js

• Maven-like but easier to use, using JavaScript

Recommended Tools II JSLint/JSHint – mandatory for all JS exceeding two lines

• jslint.com – it will hurt your feelings

• Available as Eclipse Plugin as well A JavaScript Uglifier

• Reduces JavaScript code by 50% to 90% SASS/LESS

• if you don’t know it yet, get to know it, it helps for a lot

Recommended Tools III Multiple browsers(!)

• Use two or three on your machine

• Plus a browser farm (e.g. browserstack.com) Cloud Foundry – for automatic deployment on IBM Bluemix Selenium – automate UI Tests during team development Multiple Connections instances for Test purposes

• Different Databases

• Different Versions

• Different OSes

Our Landscape

IBM Connections: 4.5

IBM Connections: 5.0

Local Clone of Repository

IBM Connections: 5.5

Eclipse IDE

JazzSCM

Jazz CI Server

IBM Bluemix

Maven (incl. Grunt)

Manage

Test

Pull

Checkout

Commit

Push

Clone

Fetch

Build and TestManage HostsDevelop

Wrap up

We Have Covered• Connections on cloud and on premises is different for

developers• Questions you have to answer in respect to your architecture• Ways to integrate your application into IBM Connections• Tools and Landscape of Connections Application Development

Thank youContact us at:

• pedestal #100

• michael.gollmick@timetoact.de

• http://connections-apps.com

Acknowledgements and DisclaimersAvailability. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates.

The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any participant. While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided AS-IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this presentation or any other materials. Nothing contained in this presentation is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

Acknowledgements and Disclaimers cont.© Copyright IBM Corporation 2015. All rights reserved.

• U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

• IBM, the IBM logo, ibm.com, Rational Software, Team Concert, WebSphere, WebSphere Liberty Profile, Bluemix, Social Business Toolkit, Connections and Connections Cloud are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml

[Insert any special 3rd party trademark names/attributions here]

Other company, product, or service names may be trademarks or service marks of others.