IBM Sametime Browser IM Toolkit

IBM Sametime 9.0 Workshop

Author: Paul GodbyEcosystem DevelopmentLast Updated: November 12, 2013


Lab Manual

Building Web Applications with theBrowser IM Toolkit

NOTE: In this lab you will be writing code. If you are not a developer (or if you don't feel like typing everything)you can choose to copy/paste the code from the lab solutions files located at:

C:\labs\solutions\IDR-PROXYAPI

COPYRIGHT IBM CORPORATION 2013. ALL RIGHTS RESERVED.IBM Ecosystem Development

1


Introduction:The IBM Sametime Browser client is a product in the Sametime family, the leading enterprise Instant Messaging and Web Conferencing product and the platform for IBM’s Unified Collaboration (UC2) strategy. The Sametime Browser client enables advanced users to be more productive and assists forward-looking organizations to leverage their internal knowledge to act in real time to ever-changing market and business situations.

In reality, the Sametime browser client is a manifestation of the toolkit. While the pre-made client providesSametime features, the real power of the product is in allowing the creation of communications-enabled business processes. In other words, web applications can be given a new degree of interaction, where the users of a web site can directly interact with each other, or with others who are connected to Sametime.

Description:The purpose of this lab is to introduce you to the Browser IM Toolkit. This toolkit allows you to build web applications that communicate via REST to the Sametime Proxy server. The Sametime Proxy server essentially acts as a "middle-man" for clients that need to communicate via HTTP to the Sametime Community server. It's job is to translate communication from the HTTP protocol to the Virtual Places (VP) protocol, and vice-versa.

The Browser IM Toolkit allows you to build your own Sametime Proxy server applications. A set of Dojo widgets has been provided so that you can quickly pick and choose which functionality to include in your application. After some initial page setup and configuration, it can be as simple as adding a few DIV tags to bring Sametime functionality to your site!

Objective:This lab will explain the following tasks:

How to embed livenames in a webpage

Invoke pre-made Dojo UI widgets for additional webpage functionality

Modify the Sametime Browser client


2


Procedure:

SERVER SETUP

In order to complete this lab exercise, the following servers will need to be running: LDAP, IBM SametimeCommunity server, IBM Sametime Proxy server.

Choose one of the following options below to prepare your server environment for this lab.

(Option 1) Start all IBM Sametime services

1. Follow the instructions in the document: How to Start Up Sametime 9.0 with Audio / Video

(Option 2) Start ONLY the IBM Sametime services required for this lab

1. Configure the hosts file using the instructions in the document named in option 1

2. On the desktop, double-click the script: startLDAP.bat

3. On the desktop, double-click the icon: IBM Domino Server

4. On the desktop, double-click the script: startProxy.bat

LOG IN SOME DEMO USER ACCOUNTS

In this lab, you will be writing some code to embed IBM Sametime livenames into a webpage. A page full of“offline” users isn't that interesting, so we have provided a script for you to log in a few demo accounts. This willallow you to see how a real livename appears in the page with various status and message settings.

Step 1 A command line script has been provided to log in a few demo user accounts. In a command window, enter the following commands to begin executing this script.

cd c:\labs\STDA

c:\IBM\Domino\jvm\bin\java -jar STDA.jar livenames

Step 2 You should see some messages appear when the users start to log in.

Step 3 Leave this command window open and proceed to the next section.


3


PREPARE A PROJECT USING THE ECLIPSE IDE

The Eclipse IDE is free and contains tools for creating Web applications, including editors for JavaScript, HTML,CSS, and XML. Best of all, this IDE is free to use. Visit www.eclipse.org/downloads for more information.

Note: You are using Eclipse Classic with the “Eclipse Web Developer Tools” add-on packages.

Step 4 On the desktop, double-click the “Eclipse” icon to start the Eclipse IDE.

Step 5 In the Workspace Launcher window, you will select a location for your development workspace.A workspace is a development profile that contains your projects, folders, files, and settings. Enter the following information and click OK.

Field Value

Workspace C:\labs\workspaces\sametime_web

Step 6 If you see the Lotus Expeditor Toolkit Configuration dialog, click Cancel.

Step 7 If you see the Welcome to Eclipse page, click the Workbench button on the right.

Step 8 From the Eclipse file menu, choose File → New → Project...

Step 9 In the New Project wizard, choose Web → Static Web Project and click Next.


4

http://www.eclipse.org/downloads


Step 10 In the New Static Web Project wizard, enter the following information and click Finish.

Field Value

Project name IDR-PROXYAPI

Step 11 If asked about switching to a Web Perspective, click Yes.

Step 12 From the Eclipse top menu bar, click Window → Preferences

Step 13 Expand General → Editors → Text Editors

Step 14 On the right, place a check next to the option “Show line numbers” and click OK.


5


CREATE A HTML TEMPLATE FILE

There are a series of steps needed to configure the page for any Sametime Proxy application. These steps willbe repeated multiple times throughout the lab as new HTML files are created. To ease the lab along, we'vecreated a HTML template file containing this setup code. When you create new HTML files, you will be able touse this template as a base starting point for your application.

Step 15 You will need to create a new Eclipse template that can be used when you create a new HTML file. In the Eclipse IDE, choose Window → Preferences.

Step 16 In the preferences pane on the left, expand Web → HTML Files → Editor → Templates.

Step 17 On the right, click New... In the New Template dialog window, fill out the fields as follows:

Field Value

Name Sametime Proxy

Context New HTML

Description IDR workshop exercises

Step 18 The Pattern field will contain the body of your template. Luckily for you, this text has already been included in the image! Using Windows Explorer, double-click the following file to open it:

C:\labs\solutions\IDR-PROXYAPI\stproxy_template.txt

Step 19 From the Notepad file menu, choose Edit → Select All. Follow up this action by selecting Edit→ Copy.

Step 20 You've copied the HTML template file to the Windows clipboard. Return to the Eclipse IDE. Click in the Pattern field to make it the active destination. Right-click again and choose Paste.

Step 21 Once you've finished pasting the HTML code into the Pattern field, click OK.

Step 22 Click OK to close the Preferences window.


6


Step 23 For your reference, here's the code from the template. A description of all of the code in this template will occur later in the lab. For now, continue to the next section.

<html><head>

<title>IDR Sametime Workshop</title><meta name="Author" content="Paul Godby">

<script type="text/javascript">var stproxyConfig = {

server: "http://sametime9imvm.demos.ibm.com:9081",tunnelURI:

"http://sametime9vm.demos.ibm.com/stproxy/tunnel.html",isConnectClient: false

};var djConfig = { parseOnLoad: true };

</script>

<script type="text/javascript" src="http://sametime9imvm.demos.ibm.com:9081/stwebclient/latest/dojo.blue/dojo/dojo.js"></script>

<script type="text/javascript" src="http://sametime9imvm.demos.ibm.com:9081/stwebclient/latest/include.js?widget=widgets&auto=false"></script>

<script type="text/javascript">function loggedIn(person) {

console.debug(person.id + " logged in successfully");}

function errorHandler(reason, error) {console.debug("Error [" + error + "]: " + reason);

}

function login() {var user = "dmisawa";var pwd = "passw0rd";var status = stproxy.awareness.AVAILABLE;var msg = "I am available";stproxy.login.loginByPassword(user, pwd, status, msg,

loggedIn, errorHandler);}

stproxy.addOnLoad();</script>

</head><body class="tundra">

</body></html>


7


CONFIGURE THE OPENAJAX HUB

The Sametime 8.5.2 Proxy server introduced the OpenAjax Hub. This technology provides a mechanism fordealing with the same-origin security policy that is in place in modern browsers. Basically, this is a browsersecurity measure to prevent cross-site scripting (XSS) attacks. The OpenAjax Hub uses a series of iFrames toallow your Proxy application to be hosted on a server outside the Proxy domain. In order to use the OpenAjaxHub in your application, you will need to reference a tunnel.html file. This file is included in the Sametime SDKand should be placed on the same HTTP server as your web application.

Step 24 In the Package Explorer, expand your current project and right-click the "WebContent" folder. Choose Import...

Step 25 In the Import window, choose General → File System and click Next.

Step 26 Browse to the following directory and click OK:

C:\labs\st9sdk\client\stproxy\samples

Step 27 In the Import window, place a check mark beside the following files and click Finish.

Field Value

Files tunnel.html

Step 28 In the Package Explorer, double-click this file to open it and review it's contents. When finished, close the file.

EMBED THE FULL IBM SAMETIME WEB CLIENT

In this exercise, you will learn how to embed the full Sametime Web Client into a page. This will give your usersthe full client experience in the context of your own application.

Step 29 In the Package Explorer, right-click the "WebContent" folder and choose New → Other...

Step 30 In the New dialog window, choose Web → HTML and click Next.

Step 31 In the New HTML Page window, enter the following information and click Next.

Field Value

File name stws1.html


8


Step 32 That hard work creating a new HTML template in the Eclipse IDE is about to pay off! Select the“Sametime Proxy” template and click Finish to create the new HTML file.

Step 33 The new HTML file, stws1.html, will open in a text editor and already contain all of the setup code that will be necessary for the following exercises! This will alleviate the need to type the same thing over, and over, and over...

Step 34 Refer to the following table for a description of the code:

Lines Description

3 The title of the webpage

7 – 11 Configure the Sametime Proxy object. You must configure this object before pulling in the Sametime libraries with script tags!

• server = the Proxy server URL and port• tunnelURI = location of the OpenAjax hub tunnel file (must

reside on the same server as your web application)• isConnectClient = whether or not to use the locally running

instance of Sametime Connect for all actions

15 Include the Dojo libraries

16 Include the Sametime Proxy components. The URL params are:• widget=widgets → load all UI widgets• auto=false → do not attempt to automatically login!

19 – 21 A logged in event handler

23 – 25 An error handler to catch all thrown errors

27 – 33 A log in function. The parameters for the stproxy login by password function (line 32) are:

1. the login name2. the login password3. the initial Sametime status4. the initial Sametime status message5. an event handler to fire upon successful log in6. an event handler to fire if log in fails

35 A handler that will fire once the Proxy components finish loading

38 The page body must have a style class of “tundra”


9


Step 35 Now that the page is setup, it's time to embed the full web client into the page using an HTML tag. Starting at line 39, add the following line of code:

Note: The web client tag will fill it's parent container and not include a border. So, you should always apply stylerules to set the desired size and include a border. In this example, you will place the web client tag inside anotherDIV with these style rules already in place.

<div style="{width:330px; border:1px solid #000000;}"><div dojoType="sametime.WebClient"></div>

</div>

Step 36 Click Save.

Step 37 You now have everything you need for your first Browser IM Toolkit application! The next step is to place the files on an HTTP server. In this lab, you will place your exercises on the IBM Domino HTTP server used by the IBM Sametime Community server. In a command window, enter the following commands to create a new directory:

Note: Alternatively, you can use Windows Explorer to copy the files. Instructions are given using command linesto allow you to quickly and easily copy files in future steps using the command history feature.

cd c:\IBM\Domino\data\domino\html

mkdir stproxy

cd stproxy

Step 38 Copy the entire contents of the “WebContent” folder in your Eclipse workspace to this new directory on the HTTP server with the following commands (Note: The line ends in a “space” followed by a “period”!):

copy /Y C:\labs\workspaces\sametime_web\IDR-PROXYAPI\WebContent\*.* .

Step 39 Leave this command window open. You can reuse it in future steps to recopy files and leverage the history feature (press the UP/DOWN key(s) to cycle through the command history) and not have to retype the command each time.


10


Step 40 Open a web browser and navigate to URL: http://sametime9vm.demos.ibm.com/stproxy/stws1.html

Step 41 As you can see, a single DIV tag allows you to embed the full Sametime Web Client in any webpage.


11


Step 42 Log in with the following user credentials and experiment with the Web Client. Take special note of the default menus. In particular, note the Send Announcement menu. In the next few steps, you will learn how to remove unwanted menus from the client.

Field Value

User name dmisawa

Password passw0rd

Remember me << unchecked >>

Step 43 In your environment, let's say you want to remove the ability to send announcements from the Web Client for all of your users. You can remove any menu from the client by adding some additional parameters to the stproxyConfig object.

Step 44 Return to the Eclipse IDE. Using the stproxyConfig object, you can choose to disable any of the file menus in the client. You can disable main window menus, livename menus, or chat window menus. All of the identifiers for each individual menu item are located in the SDK documentation. You simply find the identifier for a particular menu and set it to “false”.

Step 45 At the end of line 10, add a comma and hit the <Return> key. On the now blank line 11, add the following lines of code:

plugins: { mmpSendAnnouncement: false }

Step 46 When finished, your stproxyConfig object should look like the following:


12


Step 47 Click Save.

Step 48 Return to the command window where you entered the copy command and leverage the history feature to recopy the files to the HTTP server.

Step 49 Return to the browser and refresh the page. Return to the Tools menu. The Send Announcement menu has vanished!

Step 50 You can also add your own custom menus to the client. This will allow you to invoke your own custom actions based upon user input. Return to the Eclipse IDE.

Step 51 At line 37 (before the closing script tag!), add three blank lines so that lines 37,38,39 are all blank.

Step 52 You will need to define some code to add your new menu item. In this example, you will add the new menu item to the existing Tools menu. Your code will also provide an onClick handler to perform actions whenever the menu is clicked. In this example, you will simply display an alert box. At line 38, insert the following code:

stproxy.uiControl.addMainMenuPlugin({id: "myNewMenuID",label: "MyItem Number 1",menuId: "stproxy_toolsMenu",isShowEntry: function(widgets) {

return true;},onClick: function(mainWindow) {

alert("You clicked me!!");}

});


13


Step 53 Click Save.


Step 55 Return to the browser and refresh the page. Return to the Tools menu. Your new menu, MyItem Number 1 will appear and display an alert box when clicked!

EMBED A LIVENAME (STATIC TAG)

You can add an instance of a livename to a webpage. The livename will show the current Sametime awarenessstatus of a user. You can also double-click on the name of any online user to begin a chat.

Step 56 Close the browser. Return to the Eclipse IDE and close any open files.




Field Value


Step 60 Select the “Sametime Proxy” template and click Finish.

Step 61 You can embed any livename in a page with a single DIV tag. On line 39, add the following line of code:

<div dojoType="sametime.LiveName" userId="fadams"></div>

Step 62 The value for the userId attribute can be any string that can be resolved as a user in Sametime.For example, it could be the CN or mail attribute from LDAP. Click Save.


14



Step 64 Return to the web browser and navigate to URL:

http://sametime9vm.demos.ibm.com/stproxy/stws2.html

Step 65 You should see the livename, but it will show as Offline. Why is that? Well, we haven't logged in to IBM Sametime...yet.

Step 66 Return to the Eclipse IDE. Review code lines 28 - 32. You will be logging in as user "dmisawa"with a password of "passw0rd". Line 30 declares the initial Sametime status (other options are documented in the SDK documentation). Line 32 will actually perform the login. Refer to the table in an earlier section for a full description of the parameters.

Step 67 Line 35 in the code is a "kick-off" point for the application. The stproxy.addOnLoad function willbe called once all of the Sametime Proxy libraries have been downloaded and the page finishes loading. This ensures that everything will get setup properly before your code begins executing.

Step 68 On line 35, inside the addOnLoad function, add a call to the login function. When finished, line 35 should look as follows:

stproxy.addOnLoad(login);

Step 69 Click Save. Now, when this webpage loads, the user will be automatically logged in.


Step 71 Return to the browser and refresh the page (you may need to hold down the <Shift> key to clear the cache!). Frank Adams livename should now light up with that familiar green color!

Step 72 Congratulations! You've included a static livename in a webpage. However, there are times where names may need to be dynamically loaded. Using the Browser IM Toolkit, you can use Dojo and DHTML techniques to add new livenames to any webpage (without reloading the entire page).


15


EMBED A LIVENAME (PROGRAMMATICALLY)

You can also create livenames programmatically. For example, if your site calls a web service to obtain adynamic list of available Help Desk associates, you can embed their livenames in a website after the initial pagehas finished loading.





Field Value





Step 79 Click Save.

Step 80 In a production environment, you would probably have code to retrieve names from a back-endservice for your application. In this lab environment, we will just hard code some additional names for demonstration purposes. We will then loop through these names and programmatically add them to the existing page. At line 36 (before the closing script tag!), add three blank lines so that lines 36,37,38 are all blank.

Step 81 At line 37, add the following function:

Note: If you just add the livenames to the DOM, they will appear on a single line from left to right. To get thenames to appear in a list one on top of the other, you will need to also include your own BR or P tags.

function addNames() {var users = new Array("fadams","tamado","acandrick","jhaj","gmoor");for (var x=0; x < users.length; x++) {

var livename = new sametime.LiveName({ userId: users[x] });dojo.byId("names").appendChild(livename.domNode);dojo.create("br", null, "names");

}}


16


Step 82 As you can see, an instance of a Sametime LiveName object will get created for each user. This object will then get appended to the DOM to a DIV tag with an ID of “names”. You will want to kick this function off with a button click. At line 49, between the existing BODY tags, add the following code:

<div dojoType="dijit.form.Button" onClick="addNames()">Add Names!</div><p/><div id="names"></div>

Step 83 Click Save.


Step 85 Return to the web browser and navigate to URL:


Step 86 Click the Add Names! button to invoke your new function and programmatically add new livenames to the page.

Step 87 Feel free to experiment with the livename. Click a name start a chat, send an announcement, or view the business card. You can also double-click a name to begin a chat. When finished, continue on with the exercises.


17


CLICK TO CHAT

You can use the underlyig models of the Browser IM Toolkit to build web applications that are not reliant upon aspecial UI or even the IBM Sametime Proxy Dojo UI widgets provided by the SDK. For example, you can use anexisting link or button on a webpage to start a chat session with an IBM Sametime user.

In this example, you will simulate a support website. In a production scenario, you would likely call some back-end service to retrieve the name of the next customer service representative from a queue. Once that name isreturned, you can then use the Sametime LiveName model to programmtically begin a new chat session. Mostimportantly, you can do all of this under the covers (without UI interaction) to provide a seamless experience forthe end users.





Field Value





Step 94 Click Save.

Step 95 Thus far, you have been logging in a specific user to the Sametime Proxy for instant messagingand awareness capabilities. In a customer support scenario, you may not have this luxury. So,in this exercise, you will login an anonymous user.

Step 96 Inside the existing login function, remove lines 28 – 32. Leave line 28 blank. When finished, the login function should look as follows:

Step 97 On line 28, inside the login function, add the following line of code:

stproxy.login.loginAsAnon("Guest", stproxy.awareness.AVAILABLE, "I am available", loggedIn, errorHandler);

Step 98 Click Save. Now, when the page loads, a new guest user will be logged in anonymously.


18


Step 99 Next, you will want to add a "Click to chat" button in the UI. On line 35, add the following line ofcode:

<div dojoType="dijit.form.Button" onClick="startChat()">Click to chat...</div>

Step 100 As you can see, the button will call the startChat function when clicked.

Step 101 At line 32 (before the closing script tag!), add three blank lines so that lines 32,33,34 are all blank.

Step 102 At line 33, you will need to add a new function to programmatically create a livename model and start a chat session. In a production scenario, you would likely call some service at this point to retrieve the user name of the next support representative in a queue. In this example, we will just hard code the name. Add the following code.

function startChat() {var model = stproxy.getLiveNameModel("fadams", false, false);model.onUpdate = function() {

stproxy.openChat(model.id);}

}

Step 103 In the previous function, you are creating a livename model. This model is a non-UI representation of a Sametime livename. After obtaining the model, we can use it's properties to invoke various Proxy functionality. In this case, you will use the openChat API function with the user id resolved from the livename model.

Step 104 Click Save.


Step 106 Open a new web browser instance and navigate to URL:


Step 107 Click the Click to chat... button. Allow any popups (if necessary).

Step 108 As you can see, a new chat window instance will be started between the current guest user and user “fadams”.


19


Summary:

In this lab, you learned some of the basics of the Browser IM Toolkit that allows you to build web applications thatleverage the IBM Sametime Proxy functionality. You can embed the premade Dojo widgets directly in your page,or you can create any instance of the widgets programmatically for dynamic websites. Finally, you also learnedhow to use the underlying livename model to resolve a Sametime user name and begin a chat session.

With the skills you just learned, you can begin integrating real-time communication features into your existing webapplications today!


20

Software

IBM Sametime Browser IM Toolkit