Tuesday, June 17, 2014

Get your application integrated within IBM Connections

Since I moved to TrilogGroup, I got several requests on how we achieved the ProjExec integration with the IBM collaboration platforms, as it just looks part of it. In particular, the IBM Connections one, where the users feel like they never left Connections. We keep the same user experience than any other Connections application. This includes the same navigation bar, the same look and feel (a.k.a. OneUI), the same authentication mechanism... Some of the techniques being used are documented and supported by IBM, but others are just the result of our engineer’s inventiveness.

Let me talk today how the navigation bar can be integrated into a third party application. IBM SmartCloud for Social Business provides an easy developer experience with a well document reusable component. There are multiple articles on the subject, so I won't expand on this.  But what about IBM Connections on-premises? IBM does not provide a similar, reusable component.  Nevertheless, ProjExec does this integration, as shown below. What is the magic behind it?


Let's talk about some solutions for your own applications.

Disclaimer: This is not documented by IBM, nor it had been communicated to me by IBM. Use the technique exposed bellow as your own risk!

One solution is to load in the main application page the same files and <script> tags than Connections, in the same order.  But this strategy has some issues:
  • It is fragile. What if the next version of Connections adds/renames/removes tags or files? Your application has to be modified accordingly. And it also has to adapt to the different versions of Connections. This can quickly become a maintenance nightmare.
  • What about commons files like Dojo? Should they come from your own application or from the Connections server? You can face some weird issues if you use the former.
  • The JavaScript files and the HTML+ JS tags must be loaded and executed in the right order within the page. It is very important, else the page will just break.  Moreover, the use of third party additions to Connections makes it even trickier. How can we guarantee that the right execution order is enforced?
But wait, there is an even smarter solution. The thinking is: what displays IBM Connections pages the best? Obviously, it is IBM Connections itself :-). So instead of loading Connections pieces within your application, just load your application within Connections. In short, get an existing Connections page and inject your own content in its body, replacing the existing one. That way the common page components, including the navigation bar, are properly loaded and executed.

To make it real, the first thing you have to do was to identify the simplest possible Connections page. A page that has a simple static body you can easily replace with our own content.  After browsing the different pages, it looks like the search page /search/web/jsp/toolsHomepage.jsp is a pretty good candidate. Note that this can be simplified if you deploy a specific empty page, with the headers, within the Connections WAR files. But that requires some Connections customization. If you want to use what already exists, then the search page is good enough.

Then you have the choice of doing the work on the server or the client side:

  • On the server side, a piece of code would call the Connections page, grab the HTML markup, remove the undesired pieces and inject its new content in the body. Once done, the ready-to-go page can be sent as a whole to the browser. I can truly imagine an XPages custom JSF ViewRoot renderer doing the job :-)
  • On the client side, it is a bit more complex, because you need to mash-up the Connections page within your browser, then inject the different fragment at the right place, in the right order. But, on the other hand, it does not depend on any server side technology.

Here is a pseudo implementation of the client side solution. First, you need to start with basic html page similar to this:
<html>
<head>
  <script src=’connections-integration.js’>
  <script src=’<path to jquery>/jquery.js’>
  <script>/* inline JS #1 that grabs the Connections page*/</script>
  <script>/* inline JS #2 that inserts the Connections header*/</script>
   … <!—Your own header tags -->
</head>
<body>
  <script>/* inline JS #3 that inserts the Connections body*/</script>
   … <!—Your own page body and footer -->
  <script>/* inline JS #4 that inserts the Connections footer*/</script>
</body>

1- The first statement in the <head> tag is a reference to your custom JavaScript file (connections-integration.js), containing all the necessary code. It should be included first in the page, right after the <head> tag. Optionally, you can also include JQuery as it makes easier all the DOM operations. The JavaScript inline tags (JS #1,2,3,4) will simply call functions defined in your custom JavaScript file.

2- The JS #1 code emits a request to the Connections server, grabs the page, parses the markup, splits it into 3 parts and saves the result into a global variable. The 3 parts are:
    • Head.
      It is a copy of the <head> tag from Connections, with some content removed. For example, the <title> is removed as your app will obviously come with its own title. This is also true for all the unnecessary <meta> tags. A quick JQuery request does the trick.
    • Body.
      It contains of the <body> tag coming from Connections,  with the main content (#lotusmain) and the search bar (.lotustitle2) removed.
    • Footer.
      This is a specific part of the <body> tag. But it is an important one as some components, like Connections Mail, are injecting their code at the bottom of the page, for performance reasons. So this footer should be inserted as the bottom of your the page. You can simply remove the <ul> tags if you don’t want any Connections footer content to be displayed.
3- The other inline <script> tags (#2, #3, #4) insert the different parts at the right places in the page. To respect the execution order of Connections, these parts must be inserted and executed synchronously. This cannot be achieved with DOM insertion as the script tags won't be loaded and executed synchronously. But, fortunately, the old decried document.write() capability does the trick. The markup is converted into a string and then written on the fly to the document using this function.

There are other subtleties to make it work properly. For example, the ‘login’ button in the toolbar redirects to the last page loaded by Connections. But a quick inspection of the URL shows that there is a logoutExitPage parameter pointing to the page to redirect to. This can be set by overriding the lconn.core.auth.getLogoutUrl function.

Although this technique allows a great integration of a third party application with Connections, we would all prefer IBM to come with a supported solution, as it provides for SmartCloud. Well, with some enhancements :-) I'll be happy to share my ideas with IBM. I'm sure you too, so please join your voice to mine. By the meantime, I hope this solution will help you.

Here we go...

I know, it took me time, don't tell me. But here we go, I'm opening my own blog. I'll be focusing on IT technical articles, with of course an emphasize on IBM related technologies. But not only...

Do all the questions have elementary answers? Certainly not! But still, information sharing through a blog can help everybody. First the readers, as they can grab some experience and knowledge, and share there own experience within the comments... Then the writers, as it forces them to formalize their thinking, and evolve this thinking based on the feedback. Questions can then have obvious answers, and thus the "Elementary my dear Watson" makes sense...

As an irony of history, Watson was learning from Sherlock Holmes more than a century ago. Nowadays, we are all going to ask IBM Watson questions. Watson is now the one giving the answers, while still learning from us. I love the relation, even though the IBM name actually comes from T.J.Watson.