The Social Business Toolkit SDK (SBT SDK) provides tools for creating applications that leverage the social-enabled IBM products such as Connections, Sametime, and SmartCloud for Social Business. Included in the SDK is a playground environment where you can experiment with the tools and techniques of social business application development.
There are several installation options available for the SDK. You can use the Tomcat server that is distributed with the SDK, or you can use your own installation of Tomcat, WebSphere Application Server, Portal, or Domino.
This section describes the steps that are required to install the IBM Social Business Toolkit SDK development environment. This environment uses the Eclipse IDE and an embedded Tomcat server which allows you to build socially enabled applications on your local machine.
The installation and configuration procedure of Social Business Toolkit SDK includes the following steps:
- Installing the Social Business Toolkit SDK
- Registering OAuth applications on the IBM Connections server
- Configuring the Eclipse IDE to run the embedded Tomcat server
- Configuring the SBT SDK and Eclipse IDE for social application development
- Verifying the Social Business Toolkit development environment installation
Installing the Social Business Toolkit SDK
The Social Business Toolkit SDK is a no-charge application available from OpenNTF.org. It includes the SDK libraries, sample applications, source code, and a Tomcat server for configuring a local development environment.
You can download the SDK from here: http://ibmsbt.openntf.org
This environment was created using the January 25th, 2014 release of the SDK. You can see all available versions posted here
To install SBT SDK, in a terminal window, unzip the downloaded SBT SDK file. In our example, we place the zip file in the /residency
directory and unzip the file with the following commands:
Register OAuth applications
You can use the wsadmin commands to register the Social Business Toolkit SDK sample applications for OAuth access:
- In a terminal window, start the wsadmin utility and prepare the OAuth command environment with the following commands:
./wsadmin.sh -lang jython -user wasadmin -password passw0rd
- You have initialized the OAuth administration environment. To register the “sbt.sample.web” application, enter the addApplication OAuth admin command, as follows:
where the first parameter represents the application identifier (appId), the second parameter is the application descriptive name (appName), and the third parameter is the callback (redirectURI) address to redirect to when the application has been granted authorization.
The appId and appName values can be anything you like. The redirect URI determines where the response from the server is sent.
- Aftre registering the “SBTK” application, you should retrieve its client secret using the following command:
- (Optional) Alternatively, you can see currently registered applications, including the secrets, by issuing the following command:
- Copy the "SBTK" client secret to the clipboard for pasting it into the sbt.properties file in a later step. To copy the client secret, highlight it and right-click on the highlighted area (note: highlight only the text inside the quotes). Select Copy from the pop-up window.
- Exit the wsadmin utility with the following command (keep the terminal window open):
Now that you register the SDK sample applications with the IBM Connections server for Oauth access, you are ready to configure the Social Business Toolkit to match your environment.
Configuring the Social Business Toolkit
The Social Business Toolkit SDK uses a properties file for much of the configuration of the SDK. Using properties file allows developers to focus on the code relevant to the current task without unnecessary overhead. For example, the properties file contains information about the target IBM Connections server and the Oauth details for registered applications. This allows the developers to streamline their code and not have to "hard code" server URLs, and so on.
Complete the following steps to configure Social Business Toolkit SDK:
- In a terminal window, make a backup copy of the original the sbt.properties file, and then open it for editing, with the following commands:
cp sbt.properties sbt.properties.bak
- For each property listed below, update it to the specified value. In this example, we are only concerned with properties relevant to the IBM Connections system. We do not access the IBM SmartCloud for Social Business.
- Save and close the sbt.properties file. Close the text editor.
- Close the terminal window.
Configuring the TrustedExternalApplication role for the WidgetContainer
By default, IBM Connections only allows users to post to their own activity stream. However, when a third party application is posting events to the activity stream in IBM Connections, the third party application generally wants the ability to post to any user's activity stream. To do this, you must assign a designated user the trustedExternalApplication
The user assigned here corresponds to the "connections.app.as.user" entry in the sbt.properties file.
Complete these steps to assign the trustedExternalApplication
role to a user:
- In a web browser, start the IBM Connections Integrated Solutions Console console:
- Log in with the following credentials: User name: wasadmin, password: passw0rd
- On the left, select Applications → Application Types → WebSphere enterprise applications
- On the right, click the link for WidgetContainer (it might be on page 2).
- Under the Detail Properties section, click the Security role to user/group mapping link.
- On the next page, check "trustedExternalApplication" and click Map Users...
- In the Search and Select Users section, search for "dmisawa" and click Search.
- From the Available list, highlight "DMisawa" and click the right arrow to move his name to the Selected list. When finished, the Selected list should look the following figure:
- Click OK. You should see "DMisawa" under the mapped users for the "trustedExternalApplication" role.
- Click OK to return to the Configuration page, click the Save link at the top.
- Log out of the Integrated Solutions Console and close the browser.
In this configuration example, we configure the Eclipse IDE to use an embedded Tomcat server to host the SDK samples. You can also leverage this Tomcat server to build and test your own socially enabled applications.
- In a terminal window, unzip the Tomcat environment provided by the SDK with the following commands:
- OAuth support requires the use of the secured (SSL) HTTP port for the redirection URI. To activate SSL support in Tomcat, make an adjustment to the location of the keystore file (without this adjustment, the Tomcat startup returns the "File not found" error trying to locate the keystore file and SSL fails to enable). The keystore file location and other ports related configuration is maintained in the Tomcat server.xml document.
In the terminal window, enter the following commands to open the Tomcat configuration file:
- In the server.xml document, search for the "keystoreFile: keyword and change its value
from the "conf/keystore" relative path
to the "/labs/sbtsdk/tomcat/apache-tomcat-7.0.30/conf/keystore" absolute location in your file system.
- Depending on the servers you have installed on the machine, you might also have to alter the default HTTP ports used by Tomcat. In this environment, the default (non-SSL) HTTP port value of 8080 is already being used by Domino. To avoid the conflict, modify the port number as follows:
Locate the section for the non-SSL HTTP/1.1 Connector. In this section, change the default value of "8080" to "8081". (To find this section quickly, just search the document for "8080".) When finished, your XML should look like the following:
Note: The default secured (SSL) port number of 8443 for Tomcat should work fine in this environment. If you msut change this port, you make this modification in the same server.xml document.
Note: If the default secured (SSL) port number is changed, the "redirect URI" specified during the SBTK application OAuth registration process (in earlier steps) must be modified to reflect the updated value.
- Save and close the file. Close the text editor.
Importing the SBT SDK projects into the Eclipse IDE
Complete the following steps to import the sample applications into the IDE:
- On the desktop, double-click the "Eclipse" icon to start the Eclipse IDE.
- In the Workspace Launcher window, select a location for your development workspace. Enter the workspace directory and click OK.
- If you see the Welcome page, click the "“Go to the Workbench".
- From the Eclipse file menu, choose File → Import...
- In the Import window, select General → Existing Projects into Workspace and click Next.
- For the root directory, click the Browse... button and navigate to the /labs/sbtsdk/source directory and click OK:
- You do not need to import all projects. Deselect the following projects. You will not need them:
- Click Finish.
After Eclipse builds your workspace, the projects should appear in the Project Explorer view on the left.
Configuring Tomcat in the Eclipse IDE
In this section, you configure the Tomcat instance from the SDK in the Eclipse IDE. This configuration allows you to launch and test the SDK samples and your own applications
- From the Eclipse file menu, click Window → Preferences.
- Expand Server → Runtime Environments.
- On the right, click Add...
- In the New Server Runtime Environment window, select "Apache Tomcat v7.0" and click Next.
- For the "Tomcat installation directory", click Browse... and navigate to the following location and click OK:
- Click Finish.
- Click OK to close the Preferences window.
- From the Eclipse top menu bar, choose Window → Show View → Other...
- In the Show View window, choose Server → Servers and click OK.
- A new Servers view tab appears at the bottom of the Eclipse IDE. Click new server wizard...
- In the New Server window, select Tomcat v7.0 Server for the server type. Leave everything else as the default values and click Next.
- In the Add and Remove resources page, click the Add All button to add all resources to your Tomcat server and click Finish.
- In the Project Explorer on the left, you should see a new "Servers" project. Expand this project to see your Tomcat server configuration.
- Right-click the Tomcat v7.0 Server at localhost-config folder and choose Import...
- In the Import window, choose General → File System and click Next.
- In the From directory field, click Browse... and navigate to the /labs/sbtsdk/config directory and click OK.
- On the right, place a check mark beside "sbt.properties" and click Finish.
Verifying the Social Business Toolkit development environment installation
Before you start building your own applications, you should verify that everything was setup properly. You can do this by launching the embedded Tomcat server and viewing the Social Business Toolkit SDK samples applications.
Use the following steps to verify the Social Business Toolkit development environment installation
- In the Servers view at the bottom of the Eclipse IDE, highlight the entry for Tomcat.
- On the right side in the Servers view, click the Start the server in debug mode ( ) icon and wait for Tomcat to start.
- Open a web browser window and navigate to URL: http://localhost:8081/sbt.sample.web/home.jsp
- On the left, navigate to Connections → Profiles and select the Get Profile link from the expanded folder.
- You should now see the Frank Adams' profile information displayed in the results pane, showing his profile entry values obtained from the IBM Connections system. The output should be similar to the following:
Notice the link at the bottom of the results pane. Clicking this link displays results in a full browser page. You can use the full page mode to perform troubleshooting and debugging, for example, by enabling the Firebug and refreshing the page.
- After verifying that the SBT API works fine with the basic authentication, you should verify that the OAuth 2.0 based authorization is also operational.
On the left, expand the Authentication section and click the Connections Basic Auth link. You should see the message "You are authenticated to this endpoint" and the Logout button should be visible underneath it. Click the Logout button.
- A message confirming that you are no longer authenticated appears as shown:
Note: To make sure that you are starting with a "clean slate" as far as the user session is concerned, you should remove the browser cookies by clicking History → Clear Recent History, checking the Cookies box and clicking Clear Now.
- Expand the Authentication section again (if not expanded) and select Connections Oauth 2.0.
- In the results pane at the bottom left, click Login Popup. This action initiates the "SBTK" application request authorization sequence with the IBM Connections server based on the Oauth 2.0 protocol exchange (the "Oauth 2.0 dance" ). Depending on whether you are currently logged into Connections, you would be presented either with the Connections Login dialog window followed by the Connections Access Request window or you would just see the Connections Access Request window.
- Because you are not currently logged in, the Connections Login window should appear. log in with user name fadams and password passw0rd and click OK.
- If the login is successful, the Access Request window appears. You can either grant or deny the access. Granting the access allows the SBTK application to access user's resources in IBM Connections. Denying the access prevents the application from getting any data.
- After granting the access, you should briefly see the Access Granted window and you should be redirected back to the SBTK application (recall the "SBTK" registration process earlier in this example).
A message confirming that you are now authenticated should appear as shown below.
- If you had chosen to deny the access, the Access Denied window would have been displayed.
- Finally, you can find out which applications are currently authorized to access the user's IBM Connections information. To do that, enter the following URL in your browser:
By clicking the Revoke link on the right, you can remove the application from having the access to your IBM Connections resources.
You can now use the Eclipse IDE to begin socializing your applications.