The IBM Workplace Collaboration Services API Toolkit contains both server and client APIs. The client APIs, known collectively as the IBM Workplace Client Technology API, are the focus of this article. We discuss the toolkit contents, installation, and setup. Our goal is to help you get started developing applications for the IBM Workplace Managed Client (also known as the IBM Workplace rich client). The IBM Workplace Managed Client is built on IBM Workplace Client Technology -- the foundation for next-generation, network-centric computing.

After reading this article, you can begin setting up your development environment and exploring the toolkit features. We assume you're an experienced application developer, with some familiarity with IBM Workplace applications such as those provided with IBM Workplace Collaboration Services.

The IBM Workplace Collaboration Services API Toolkit

There are two toolkits that you can use with the IBM Workplace Managed Client. The first is the IBM Workplace Collaboration Services API Toolkit. Use this toolkit to extend the IBM Workplace Collaboration Services platform with new business components, portlets, and other features using the J2EE programming model. The IBM Workplace Collaboration Services API Toolkit includes the IBM Workplace Client Technology APIs, which we discuss in this article.

The second toolkit is the IBM Workplace Managed Client Developer Toolkit. This is a set of Eclipse plug-ins composed of wizards, templates, and builders. This toolkit helps you reduce the manual tasks involved with application development. It also allows exporting directly to Rational Application Developer. This toolkit will be described in a future article.

You can download the IBM Workplace Collaboration Services API Toolkit here. The toolkit contains the following.

Public APIs

These are APIs (Application Program Interfaces) and SPIs (Service Provider Interfaces) that you can use to extend the platform or build applications.

Guides

The toolkit includes several guides, provided in Adobe PDF format and as Eclipse Help plug-ins:

• IBM Workplace Client Technology API Toolkit User’s Guide provides information to help application developers use the toolkit to build applications to run on the IBM Workplace Client Technology platform.
• IBM Workplace Client Technology API Toolkit User’s Guide provides information to help application developers use the toolkit to build applications to run on the IBM Workplace Client Technology platform.
• IBM Workplace Client Technology Rich Client User Interface Design Guidelines consists of user interface programming tips, design practices, and coding guidelines for building applications for the IBM Workplace rich client.
• Javadoc is documentation parsed from the Java source files contained in the toolkit.
• Workplace Client Technology, Micro Edition (WCTME) Enterprise Offering Application Developer’s Guide contains coding examples and other programming help, focused on Workplace Client Technology Micro Edition.

Sample code

The following code samples for the IBM Workplace Client Technology platform are provided with the toolkit. You can install and use these samples for testing and research of the various toolkit programming methods:

• Call Center application exercises the IBM Workplace Client Technology APIs using a real-world, customer support application.
• Sample application demonstrates public APIs that are not exercised by the Call Center application.
• Order entry sample demonstrates Enterprise Offering capabilities. It uses the Web Container, Servlet 2.3, Configuration Admin, MQ Everyplace, JDBC, DB2 Everyplace, Rich Client views, and Preference Pages.
• isync sample demonstrates how to use the DB2 Everyplace synchronization engine to synchronize client data.

This article describes how to set up the Call Center and Sample application. For instructions about how to set up the Order entry sample and isynch sample, consult the IBM Workplace Client Technology API Toolkit User’s Guide.

Toolkit directory structure

As mentioned previously, the toolkit contains both IBM Workplace Collaboration Services APIs and IBM Workplace Client Technology API content. All client-related sources (except for the documentation files) are contained in the wct subdirectory.

After installation, expanding the directory structure reveals that there are several folders under each major item (imspi, lwpapi, mailspi, and wct). For more on the specifics of each of these subfolders, consult the documentation provided with the toolkit.

Back to top

Development environment requirements

At minimum, you need the following for IBM Workplace Managed Client development:

Back to top

Setting up the development environment

Setting up the development environment properly ensures that you get the most out of the toolkit. This needs only to be done once! The major steps to do this are:

1. Install and setup/configure the IBM Workplace Collaboration Services server. This may already be done in your environment. The latest version of the toolkit supports both the 2.5 and 2.5.1 releases of the IBM Workplace Collaboration Services server.
2. Install the IBM Workplace Client Technology server-side installer.
3. Use the download page on the server to download and provision the IBM Workplace Client Technology Platform runtime.
4. Install and setup/configure the IDE. As mentioned in the previous section, this can be Eclipse or Rational Application Developer.
5. Install the Workplace Client Technology (WCT) sample applications from the IBM Workplace Collaboration Services API Toolkit.

These steps are described in the following sections.

Back to top

Install and setup/configure the IBM Workplace Collaboration Services server

The server is required, as it is used to provide and manage the IBM Workplace Managed Client. Browser clients also interact with the server. The installation guide for IBM Workplace Collaboration Services has all the detail you need; here are a few general tips:

• The server does not need to be running the same operating system platform as the IBM Workplace Managed Clients.
• The server must be running (in other words, operational). There is an easy way to check whether or not a server is up: from the appserver directory, enter the command serverstatus –all.
• You should have Administrative access to the server.
• If your machine has sufficient memory size, you can have the server and the client on the same physical machine.

Back to top

Install the IBM Workplace Client Technology server-side installer

The HTTP server is used as a Web server for the IBM Workplace Collaboration Services server. You need to do the following:

1. Change settings through the IBM Workplace Administrative console to allow for Managed Client support.
2. Install and configure the Workplace Client Provisioning components. The IBM Workplace Managed Client files must be installed on the server so that users can download the client and features.
3. Install the IBM HTTP server. An external HTTP server improves performance when used with the rich client provisioning server. There are two types of external HTTP servers, local and remote. A local server is on the same physical machine as the IBM Workplace Collaboration Services or the provisioning server. With a local server, performance may be slower than with a remote HTTP server. A remote HTTP server uses a separate machine, and may require a customized installation.

Allowing Managed Clients

To allow Managed Client support on the server, verify that the server is running. (Use the command serverstatus -all.) Then start your browser, and open the IBM Workplace Administrative console by entering the url http://<host>:9091/admin, where <host> is the fully qualified name of your IBM Workplace Collaboration Services server, for example, http://iwcs.isv.ibm.com:9091/admin.

Next, sign in as the WebSphere Administrator (you will need the signon and password for this). Then open the default user policy by selecting Lotus Workplace - Users - Manage User Policies - Default User Policy (see figure 1):

Page down until you get to the section titled Allowed clients, and place a checkmark beside the Rich client option (see figure 2):

While you are at it, page down and select the options to allow for Activity Explorer and Allow technical preview features. Optionally, you can select several other options, such as allowing for Productivity tools or the Lotus Notes Plugin. When you are finished, click Save and then OK. You must also select "Save to the Master Configuration" (see figure 3):

Select Logout to leave the WebSphere Administration Console.

Install Provisioning components

Follow these steps to install the IBM Workplace Client Provisioning components. These instructions apply to a Windows-based machine.

NOTE: These steps assume that you have already obtained the IBM Workplace Managed Client 2.5 or 2.5.1 from IBM. See the IBM Workplace Managed Client product page for details. You should also have already installed the HTTP server on the same physical box, called a local, external HTTP server, as described here.

Verify that the IBM Workplace Collaboration Services server is running, using the serverstatus –all command. Then in Windows, launch the setup program setupWin32.exe. Click Next and accept the license agreement. (Please read and only accept if you agree.)

Enter the name of your installation directory (for example, C:\WebSphere\Workplace Rich Client Provisioning), and choose Next to continue. Then select Typical setup, and click Next.

Supply the requested information, including Portal server directory, Portal server configuration URL, portal administrator user ID, and Portal administrator password. The configuration URL should be the WebSphere fully-qualified hostname with /lwp/config, for example: http://iwcs.isv.ibm.com/lwp/config. When you are finished entering this information, choose Next to continue.

Supply the necessary Application Server information (each item begins with WAS denoting WebSphere Application Server):

• AppServer directory
• Server name
• Cell name
• Server BOOTSTRAP_ADDRESS
• Server SOAP connector port

All of this information is found through using the WebSphere Administrative Console. When you complete these fields, choose Next to continue.

On the next screen, you must enter the value corresponding to your HTTP server root. For example, in our configuration with an external local installation, the directory is C:\IBMHTTPServer\htdocs\en_US. Then press Next to continue. Review the information displayed on the summary screen for accuracy. If everything looks OK, press Next to begin installation. During the install, you may be prompted to bring down and restart the WebSphere Portal Server. When this happens, do so, and then resume the installation.

Use the download page on the server to download and provision the IBM Workplace Client Technology Platform runtime. Developing for the client means that you will need to have the Managed Client installed for testing purposes. The IBM Workplace Managed Client is available now and can be downloaded. Figure 4 shows the browser window. Notice the download link indicating that the IBM Workplace rich client (Managed Client) and the mobile client (Micro Edition) are available for download:

Downloading the Managed Client

To download the IBM Workplace Managed Client, access IBM Workplace Collaboration Services through the IBM HTTP server, and log in as your administrative user or other user if you have already set one up. Download the client by selecting the link labeled IBM Workplace rich client. Then select the Start Download button (see figure 5). Accept any security warnings, and accept the license.

Install using the default installation directory

Specify your login credentials, as supplied by the administrator. This is generally a username and password combination, but could also include a server name. Observe the installation, including the restart process. After restart, you need to enter the Provisioning Server URL. This is usually http:// or https:// with the fully-qualified-server name and “/lwp/myworkplace” at the end. Login information can always be viewed through Preferences. In this example, the Portal URL is http://iwcs25.idr.ibm.com/lwp/myworkplace. The port is the default of 2810.

Log in as you had previously done, and validate the certificate if prompted. You are done!

Back to top

Install and setup/configure the IDE

The integrated development environment (IDE) is what you use to create and build applications. As mentioned previously, this can be Rational Application Developer or Eclipse. When deciding which IDE to use, consider the following:

• Previous experience. Have you used the IDE previously? Can you navigate it pretty well by now?
• IDE capabilities or limitations. Do you need to use one IDE vs. another because of some feature or special capability that it has?
• Extensibility. Is the application or feature you are planning to create going to be extensible? Will the IDE help you do this?
• Platform or architecture concerns. How easily can you create applications for multiple platforms or architectures?

The following table compares IDE features, guidelines, and capabilities. This is not a complete list, but is enough to provide you with information to help you select the appropriate IDE for your development needs.

Installing the IDE is pretty straightforward. Install the IDE onto a machine with the correct version and fix pack (if necessary) of the operating system.

Back to top

Install the sample applications from the API Toolkit

There are several sample applications shipped with the toolkit that you can use to illustrate IBM Workplace Managed Client capabilities and features. These samples are for example only, and not intended for production deployment. Samples you wish to use must be added to the Eclipse update site. This is a directory on the HTTP server. To use these samples, the IBM Workplace Managed Client should already be installed on your PC.

Installing the samples is a four-step process, and takes only about 30 minutes to complete:

1. Copy files from the toolkit.
2. Backup and edit the file site.xml.
3. Use XML Access.
4. Set up access levels.

The following sections explain these steps in detail.

Copy files from the toolkit

You will need to copy several files from the toolkit to the system.

NOTE: The preceding table applies to the 2.5 version of the toolkit. In the 2.5.1 version, the subdirectory names end with 2.5.1.

Backup and edit the site.xml

The file site.xml must contain a feature tag for both the Call Center and the Sample application. Locate the file site.xml under the <httpserver_home>\ht_docs\en_us\lwpupdate\wct\features directory and create a backup copy called site.old. (This is so that you can always revert to the original site.xml if necessary.) Next, edit the site.xml to add feature tags as shown here:

id="com.ibm.workplace.demo.callcenter.feature"
url="features/com.ibm.workplace.demo.callcenter.feature_2.5.0.jar" version="2.5.0"> 

id="com.ibm.workplace.samples.feature" 
version="2.5.0"> 

url="features/com.ibm.workplace.api.feature_2.5.0.jar" id="com.ibm.workplace.api.feature" 
version="2.5.0">

Add an images subdirectory to the HTTP server. Then copy all image files from the lwpapi25\wct\samples\deploy\images directory to this images directory.

Use XML Access

Although you can create portal pages manually, using XML Access is far easier, and allows you to create a portlet and page to provision the Call Center and Sample application features to the client. To use XML Access, create a subdirectory (for example, C:\tempxml) and copy the files add_rcpsdk_portlets.xml and add_rcpsdk_pages.xml from the \lwpapi25\WCT\samples\deploy\xmlaccess to that subdirectory.

At the command prompt, change to the WebSphere Portal server’s \bin directory and enter the following command to run the XML Access utility program:

xmlaccess -in D:\tempxml\add_rcpsdk_page.xml -user wpsadmin -pwd wpsadmin -url
127.0.0.1:9081/lwp/config

You must change this command to accommodate your WebSphere signon and password, your IP address, and your subdirectory name.

Set up access levels

To ensure that all users can use the samples, set the User role to all authenticated users. You must do this for each portlet with pages beginning with the string RCPSDK. To do this, log in to the WebSphere Portal Administration feature in IBM Workplace, as shown in figure 6:

Select Access – Resource Permissions - Portlets. Then search on RCPSDK and locate all the portal pages. For each of the pages, set the User role as you wish. For example, you can choose to set this to all authenticated users.

Back to top

Conclusion

Congratulations! You have now set up the IBM Workplace Collaboration Services API Toolkit. Your IDE is ready to go, and you can start using the toolkit and the samples provided to start developing applications for the Managed Client platform.

Resources

• You can download the IBM Workplace Collaboration Services API Toolkit here.
  
  
• See the IBM Workplace Managed Client product page for details on how to obtain the IBM Workplace Managed Client 2.5 or 2.5.1 from IBM.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• The IBM Workplace Collaboration Services API Toolkit
• Development environment requirements
• Setting up the development environment
• Install and setup/configure the IBM Workplace Collaboration Services server
• Install the IBM Workplace Client Technology server-side installer
• Install and setup/configure the IDE
• Install the sample applications from the API Toolkit
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers