Developing social applications with the Social Business Toolkit SDK

Intro

The Social Business Toolkit SDK (SBT SDK) is a set of libraries and code samples that you use for connecting to the IBM Social Platform. As a developer you can choose which web development skills fits you best: Java, (client side) JavaScript or XPages. Your social platform may reside in the cloud or on premise.

In this post I will give you guidelines and practical examples to get you started. I choose XPages as development environment.

Terminology

In the document terms are thoroughly used:

Term Description
SBT Social Business Toolkit
SDK Software Development Kit
DDE Domino Designer on Eclipse
XPages XPages is a rapid web and mobile application development technology
OpenNTF Open Source Community for (IBM) Collaboration Solutions
OAuth Open standard for authorization
Managed Bean Java Beans representing system objects and resources
Endpoint Encapsulates the access to a service provider, like Connections or Sametime

Installation of the SDK

Prerequisites

Before you can start with development in Domino Designer on Eclipse you need to install the SBT SDK. It can be downloaded from the following address: http://ibmsbt.openntf.org/. The files you need to work with the SBT SDK and Domino are located in folder ‘redist\domino’ in the downloaded ZIP file.

Extension Library

Another condition to be able to run the Social SDK within your XPages you need to have installed the Extension Library, available on OpenNTF: http://extlib.openntf.org/. You need to have the library installed on both Domino server and DDE.

Installation for Domino Server

You can find a set of instructions how to install the SBT SDK on an IBM Domino server on the address:
http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Social+Business+Toolkit+SDK+documentation#action=openDocument&res_title=Installing_on_Domino_Server_SDK1.0&content=pdcontent. I recommend the installation via an Eclipse Update site. As a result your Update site should display the following plugins:

Screenshot_4

 

Installation for DDE

The Domino Designer deployment of the IBM Social SDK can use the same imported update site from the Update Site NSF. On Domino Designer verify that the checkbox for “Enable Eclipse plugin install” is checked in the Domino Designer preferences. You can find a set of instructions how to install the SBT SDK on DDE on the same address:
http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Social+Business+Toolkit+SDK+documentation#action=openDocument&res_title=Installing_on_Domino_Server_SDK1.0&content=pdcontent.

Setting up a Notes application

Create a new Notes application from scratch. I called mine ‘bornsocial.nsf’. Open the Xsp Properties file in DDE. Include the following libraries:

  • com.ibm.xsp.extlib.library
  • com.ibm.xsp.sbtsdk.library

Screenshot_5

 

Authentication

The Social Business Toolkit leverages a credential store for single sign on. For OAuth for example the user tokens are stored in this repository so that users don’t have to authenticate and grant access to services like IBM Connections for every session. The OAuth application tokens are also stored in this repository so that all tokens can be managed in one central place. You can read more on the credential store here: http://www-10.lotus.com/ldd/appdevwiki.nsf/xpDocViewer.xsp?lookupName=IBM+Social+Business+Toolkit+SDK+documentation#action=openDocument&res_title=Configuring_token_stores_SDK1.0&content=pdcontent&sa=true. And it is also explained in the following video: http://www.youtube.com/watch?v=2CWD70XarX8#t=100.

In basic: the implementation of the credential store is performed by the use of a managed bean. The usage of this credential store is then defined in an endpoint. An endpoint encapsulates the access to a service provider, like Connections or SameTime.

In the Package Explorer open the faces-config.xml file:

Screenshot_6

 

Add the following lines:

<!– Token Store memory implementation –>
<managed-bean>
<managed-bean-name>CredStore</managed-bean-name>
<managed-bean-class>com.ibm.sbt.security.credential.store.MemoryStore</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

<!– Password Store memory implementation –>
<managed-bean>
<managed-bean-name>PasswordStore</managed-bean-name>
<managed-bean-class>com.ibm.sbt.security.credential.store.MemoryStore</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

Endpoint

In the first example(s) we are only going to demonstrate to connect to IBM Connections. Add the following lines:

<managed-bean>
<managed-bean-name>connections</managed-bean-name>
<managed-bean-class>com.ibm.sbt.services.endpoints.ConnectionsBasicEndpoint</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
<managed-property>
<property-name>url</property-name>
<value>https://your-connections-url.com</value&gt;
</managed-property>
<managed-property>
<property-name>authenticationService</property-name>
<value>communities/service/atom/communities/all</value>
</managed-property>
<managed-property>
<property-name>authenticationPage</property-name>
<value>/bornsocial.nsf/_BasicLogin.xsp?endpoint=connections</value>
</managed-property>
</managed-bean>

For value of managed property ‘url’ you must enter the address of your connections installation or in case you are using IBM Greenhouse for demonstration purposes you can choose ‘https://greenhouse.lotus.com’.

Login page

A custom login page will presented when a user initially tries to connect to IBM Connections:

Screenshot_7

 

The elements for the login page are in the XPagesSBT.nsf application which comes with the SBT SDK. The nsf is located in folder redist\domino. The login page consists of the following design elements:

Name Type
_BasicLogin.xsp XPage
sbtLoginPage Custom Control
sbtLoginPanel Custom Control

You can simply copy the design elements from the sample application in your application and modify them e.g. for branding.

Connecting to Connections

Your application is now ready to connect to Connections. Where you place the code to connect to Connections is up to you. A recommended approach could be to establish connections via Managed Beans.A managed bean is nothing more fancy than a registered a JAVA object.

Managed Bean

In our first example we are going to read the content under My Files in Connections. These are the files that you have uploaded and shared.

  1. Create a new Java design element (Java Class).
  2. Enter the following code:

package com.quintessens.bornsocial.sbt;
import java.io.Serializable;
import com.ibm.sbt.services.client.connections.files.FileService;
import com.ibm.sbt.services.client.connections.files.FileServiceException;
import com.ibm.sbt.services.client.connections.files.FileList;

public class ServiceBean implements Serializable{
private static final long serialVersionUID = 1L;

public FileList getMyFiles() {
FileService service = new FileService();
try {
return service.getMyFiles();
} catch (FileServiceException e){
return null;
}
}
}

Code explanation

The function getMyFiles gets handle to the FileService object. Then the getMyFiles function is called to get all the files (both private and shared) the user has uploaded in Connections. Then a FileList object is returned to the caller.

The FileList object can then be used in a suitable XPage control e.g. the DataTable or the DataView control.

Registration

In order to access the Managed Bean you have to register it. This is done in the faces-config.xml file. Open the file and add the following lines:

 <managed-bean>
<managed-bean-name>ServiceBean</managed-bean-name>
<managed-bean-class>com.quintessens.bornsocial.sbt.ServiceBean</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

You will access the bean via its name ServiceBean.

XPages

Finally we have come to a point where we can display the files that the managed bean returns from IBM Connections. I have choosen the XPages environment to do so.

Custom Controls

A best practice in XPages development is to divide functionality in individual blocks known as Custom Controls. This make it easier to re-use the functionality across your application.

Custom Control for a ‘My Files’ overview

  • Create a new Custom Control design element.
  • Add the following code to the control:

<xe:widgetContainer id=”widgetContainer1″ itleBarText=”#{javascript:return compositeData.widgetTitle;}”>
<xp:panel>
<xe:dataView id=”dataView1″ var=”file” rows=”5″ columnTitles=”true” styleClass=”filesDataView”>
<xe:this.extraColumns>
<xe:viewExtraColumn columnTitle=”Filetype”></xe:viewExtraColumn>
<xe:viewExtraColumn columnTitle=”Created”></xe:viewExtraColumn>
<xe:viewExtraColumn columnTitle=”Size”></xe:viewExtraColumn>
</xe:this.extraColumns>

<xe:this.summaryColumn>
<xe:viewSummaryColumn columnTitle=”Filename”></xe:viewSummaryColumn>
</xe:this.summaryColumn>
<xp:this.value>
<![CDATA[#{javascript:ServiceBean.getMyFiles();}]]>
</xp:this.value>
<xp:this.facets>
<xp:panel xp:key=”noRows” id=”topicsPanel2″>
<xp:div styleClass=”lotusWidgetBody”>
<xp:text>
<xp:this.value>
<![CDATA[#{javascript:return (viewScope.myFilesAvailable ? “No files found.” : “My Files unavailable.”);}]]>
</xp:this.value>
</xp:text>
</xp:div>
</xp:panel>
<xp:panel id=”summaryPanel” xp:key=”summary” style=”width:50%;white-space:nowrap;”>
<h4><xp:link styleClass=”dataViewLink” escape=”true” id=”link7″ target=”_blank” text=”#{javascript:return file.getTitle();}”>
<xp:this.value><![CDATA[#{javascript:return file.getContentUrl();}]]></xp:this.value>
</xp:link></h4>
</xp:panel>
<xp:panel id=”typePanel” xp:key=”extra0″ style=”width: 20%;white-space:nowrap;”>
<xp:text>
<xp:this.value>
<![CDATA[#{javascript:return file.getType();}]]>
</xp:this.value>
</xp:text>
</xp:panel>
<xp:panel id=”sizePanel” xp:key=”extra2″ style=”width: 15%;white-space:nowrap;”>
<xp:text>
<xp:this.value>
<![CDATA[#{javascript:var size = file.getSize();
var kilobyte = 1024;
var megabyte = kilobyte *1024;
if(size < kilobyte) {
return (size + ” B”);
}else if(size < megabyte) {
return (Math.round(size/kilobyte) + ” KB”);
}else {
return (Math.round(size/megabyte) + ” MB”);
}}]]>
</xp:this.value>
</xp:text>
</xp:panel>
<xp:panel id=”panel1″ xp:key=”extra1″ style=”width: 15%;white-space:nowrap;”>
<xp:text escape=”true” id=”computedField3″ value=”#{javascript:file.getCreated()}”></xp:text>
</xp:panel>
</xp:this.facets>
</xe:dataView>
</xp:panel>
</xe:widgetContainer>

As a result the files in IBM Connections for the authenticated user will be listed e.g.:

Screenshot_8

 

Code explanation

The DataView control is using the getMyFiles function from Managed Bean ServiceBean for data binding:

Screenshot_9

<xe:dataView id=”dataView1″ var=”file” rows=”5″ columnTitles=”true” styleClass=”filesDataView”>
<xp:this.value><![CDATA[#{javascript:ServiceBean.getMyFiles();
}]]></xp:this.value>

</xe:dataView>

It iterates through the returned FileList object and for each column values from each entry in the ‘file’ collection the value is computed e.g.:

<xp:panel id=”summaryPanel” xp:key=”summary” style=”width:50%;white-space:nowrap;”>
<h4><xp:link styleClass=”dataViewLink” escape=”true” id=”link7″ target=”_blank” text=”#{javascript:return file.getTitle();}”>
<xp:this.value><![CDATA[#{javascript:return file.getContentUrl();}]]></xp:this.value>
</xp:link></h4>
</xp:panel>

API Explorer

Use the SBT API Explorer which method each object provides:

Screenshot_10

Link: http://greenhouse.lotus.com/llapiexplorer/.

Summary

As you have seen getting started with the Social Business Toolkit is not that difficult for XPages developers. As alternative you could also choose JavaScript or JAVA if those skills fit you better. The SDK will help you understanding Connections piece by piece from a developer perspective.

In the example information is read from Connections but you can also post data. The SDK allows you to create great ‘social enabled’ applications. This can be applications that solely work with Connections or integrate with other platforms e.g. IBM Notes.

I hope to write more on the Social Business Toolkit in another post. Thank you for reading.

Patrick Kwinten

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s