Level: Advanced Hangsu Ma, Software Developer, IBM
10 May 2005 If you're interested in saving time (and who isn't), read this article and learn how to set up a system to automatically deploy updates and applications to your IBM Workplace users.
The IBM Workplace Managed Client (formerly known as IBM Workplace Client Technology, rich edition) provides a feature-rich alternative to accessing IBM Workplace products through a Web browser. The Workplace Managed Client (also known as the rich client) offers features such as offline support, synchronization, search, and document editors.
An important feature of the Workplace Managed Client is the ability to centrally manage it through a server. This includes policy-based management, provisioning, and troubleshooting. (For more information, see the developerWorks: Lotus article, "Administering the rich client in IBM Lotus Workplace.") This also includes features that allow you to automatically deploy updates to the Managed Client.
In this article, we explain how to create and configure a process for automatically deploying updates and applications to your Workplace users. This involves creating an Eclipse-based update site and a WebSphere Portal provisioning page that instructs the Managed Client how to access the update site and what updates to download from it. This process will allow you to control how and when updates and applications are deployed within your Workplace community. The process can be used to deploy new applications or updates to existing ones.
This article assumes you're an experienced developer of plugin applications, with some familiarity with Workplace and WebSphere Portal. Knowledge about Eclipse, the XMLAccess facility, and Workplace or WebSphere server management will also be helpful.
Workplace Managed Client architecture
This section takes a brief glimpse at some of the underlying technologies within the Workplace Managed Client. For more information, see the developerWorks: Lotus article, "IBM Workplace Client Technology architecture."
The Managed Client is based on Eclipse rich client technology. It consists of a bundle of Eclipse plugins and features, including views to provide the user interface. The Managed Client assembles these in a page by following instructions contained in a manifest file. (This page is equivalent to the "perspective" in the Eclipse platform.)
The manifest file is written in RCPML (Rich Client Platform Markup Language). It is an XML file that describes the attributes of the Managed Client application. The manifest file includes information such as which features the application needs, how the user interface will look, and so on.
Deploying updates
When the Managed Client is installed and configured, it requests the manifest files from the server, downloads and parses them, then downloads the plugins specified in the file and builds the Managed Client application. In simple terms, the process goes like this:
- A user installs the Managed Client. This provides the user with a Managed Client platform with some default Workplace applications.
- The user runs the Managed Client and logs into the Workplace server for the first time.
- The server pulls down the appropriate manifest (RCPML) files to the Managed Client. The files that get downloaded are determined by server settings that we will describe later.
- The Managed Client parses the RCPML files and uses this information to locate the update page and determine which updates to download. For the first login, these updates will include Workplace applications, such as Activity Explorer.
- Every time the user subsequently logs into the server, the client gets the new RCPML file from the server and checks for any available updates. If there are any, steps 3 and 4 are repeated.
The important thing to keep in mind about this process is that it is entirely automatic as far as users are concerned -- they never have to decide which updates to download, where to go to obtain them, and so on. Instead, this is controlled through the provisioning page. Both the provisioning page and update site are created and maintained by the Workplace administrator, providing central management of this process.
Therefore, setting up the process for automatically deploying Managed Client updates and applications involves two basic steps (which can be done in any order):
- You need to create an update site to upload the required plugins and features, where your users can download them and run them locally as specified by the manifest (RCPML) files.
- You must create a provisioning page on the Workplace server to provide the manifest files to the Managed Client.
The following instructions assume you are running Workplace Collaboration Services 2.5 or Workplace Services Express 2.5 with the provisioning component installed. This must be running on top of WebSphere Application Server 5.0.2.6 and WebSphere Portal 5.0.2.2. In addition, you will need a development environment such as Rational Application Developer 6.0 or Eclipse 3.0 (which you can download for free from the Eclipse Web site download page). In this article, we assume you're using Eclipse as your development environment.
Downloading the samples
We will use a simple plugin and a simple Eclipse feature as our sample Managed Client application. A "feature" in Eclipse terminology is a basic "downloadable" component. Features (which are mainly a type of manifest file) combine plugins and other features to make it more convenient to download and manage components. The sample plugin (com.ibm.wct.sample.plugin) is generated with the Eclipse new plugin wizard. The sample feature (com.ibm.wct.sample.feature) contains the plugin. You can download both the feature and the plugin here, unzip them, and import them into your workplace by choosing File - Import.
Figure 1. Sample plugin and feature
Setting up provisioning
The provisioning process allows administrators to deliver the Managed Client to users on demand. This involves server-managed roles and policy-based distribution. Provisioning requires that the Workplace provisioning component (sometimes called the provisioning server) must be installed. The IBM Workplace documentation contains instructions on how to provision the Managed Client. You can also consult the developerWorks: Lotus article, "Administering the rich client in IBM Lotus Workplace," for a good introduction to the provisioning process.
Creating the update site
As we mentioned earlier, you must create an update site from which users can download your Managed Client updates and applications. You can create this update site from Eclipse. A Managed Client update site is in fact an Eclipse update site, so the process for creating one is the same. (This helps make it easier to migrate Eclipse plugins to Workplace.)
A typical Managed Client update site consists of folders for features and plugins, a manifest file called site.xml, and optionally other folders. The folders contain files users can download to their local machines. Figure 2 shows an example Managed Client update site structure:
Figure 2. Managed Client update site structure
By default, the structure of a Managed Client update site is controlled by the file site.xml. This file resides in your IBM HTTP Server (IHS) install directory. (More on this file later.)
Before we begin, let's take a moment to clarify the relationship between features and plugins. As we mentioned earlier, features contain plugins (and sometimes other features). This makes it easier for users to download and manage groups of related plugins -- rather than download them individually, they can just download the feature. Eclipse will parse the manifest file in the feature, and download the corresponding plug-ins. Eclipse also uses the "feature" as a unit to manage its configuration. You can install, uninstall, and disable each feature.
Because the Managed Client update site is identical to an Eclipse update site, we use the Update Site Project feature in Eclipse to create the update site for our sample application. To do this, open the Eclipse PDE (Plugin Development Environment) and select File - New - Project - Plug-in development - Update Site Project. The New Update Site Wizard appears:
Figure 3. New Update Site Wizard
The New Update Site Wizard consists of the following:
-
Project name identifies the update site. This name will appear on the Web page generated by the wizard when you select the "Generate a web page listing..." checkbox.
-
Project contents identifies the location of the update site. You need to set this to \htdocs\en_US\lwpupdate\wct, which resides in the IHS install directory on the Workplace server.
-
Generate a web page listing all available features within the site generates an html file listing the available features and plugins on the update site (see Figure 4). This is only used to support Web browsers.
Figure 4. Update site features and plugins
-
Web resources location is set to web by default.
Click Finish to have Eclipse create the update site project. Next, open the update site and double-click site.xml in the left navigator. Then select the Features tab in the editor. This displays the Site Manifest editor:
Figure 5. Site Manifest editor
The Site Manifest editor lets you select and organize the features you want to include on the update site. To do this, click Add to display a list of available features.
Figure 6. Selecting features
The Site Manifest editor lists all features that reside in the current workspace. (Note that features with different version numbers are treated as different features.) Select the features you want to add to the update site. Then use the New Category button to create the categories you want to appear on the update site, and place the selected features into these categories. (Internally, this updates site.xml, which is the manifest file for the update site. The site.xml file controls which features and categories are listed on the update site. The categories are used to group a bunch of features.) When you are finished, click Build All to create the update site.
To build the update site, Eclipse parses the manifest file (feature.xml) contained within each feature to determine which plugins are associated with each feature. Eclipse then builds .jar files for each feature and plugin, and places them on the update site. When users subsequently download the feature from the update site, these .jar files (including the associated plugin .jar files) are loaded onto their local clients.
To check out the new update site, open Eclipse and select Help - Software Updates - Find and install - Search for new feature for install. Then enter the directory of the update site. You can also browse the update site by opening its URL in the browser, assuming you checked the "Generate a web page listing…" checkbox in Figure 3 (for example, http://hangsu.ibmirl.lan/lwpupdate/wct/index.html).
Editing site.xml
Your new update site contains a folder named Plugins that contains all the .jar files for each version of the plugins. There is also a folder called Features for storing features for downloading.
NOTE: In most cases, users shouldn't download individual plugins directly. To obtain a particular function, download the feature that contains the plug-ins.
You can manually add features to your update site by editing the site.xml file. For example, the following block of code adds the feature features/com.ibm.wct.sample.feature_1.0.0. Adding this code to site.xml adds features/com.ibm.wct.sample.feature_1.0.0 to the list of available features on the update site:
<feature url="features/com.ibm.wct.sample.feature_1.0.0.jar
id="com.ibm.wct.sample.feature"
version="1.0.0" >
<category name="WCT"/>
</feature>
|
The URL is where the feature lives; the id is the id setting in feature.xml. Category name identifies the update site category in which this feature will appear.
You can browse the update site by category. By default, site.xml includes a category named WCT. You can add other categories by editing site.xml. For example, the following code adds a category called WCT Sample:
<category-def name="WCT Sample" label="WCT Sample">
<description>IBM Workplace Managed Client sample applications</description>
</category-def>
|
Update site icon for the switcher bar
A small but important item to consider is the graphical icon for the Managed Client application. This icon will appear in the Managed Client's switcher bar. The file for this icon is a .png file that should be stored in the lwpupdate directory on your HTTP server. This .png file should be dimensioned as 34x32 pixels.
Creating the provisioning page
As we mentioned earlier, there are two main steps involved in setting up an automated update process in Workplace. The first we've already dealt with -- creating the update site. Now we turn our attention to the second step, creating the provisioning page on the Workplace server. When clients connect to the Workplace provisioning server, the server fetches relevant parameters (which we discuss later in this article) from the provisioning page and "placeholder" portlets that reside on the provisioning page. When the client starts up, it sends a request to the server to retrieve the RCPML that is represented by the provisioning page and the placeholder portlets. In response to the client request, the Workplace server generates a manifest file using RCPML that represents the list of available applications. The client uses the manifest to determine which applications it is required to download from the setup site and make available to the user.
In this section, we will create a provisioning page containing a placeholder portlet. This portlet contains the information needed to generate RCPML on the server side. We include a sample script that you can download and run to create your own provisioning page. (If you need help understanding some of the terminology we use in this section, consult the WebSphere Portal documentation.)
When you install the provisioning component on the server, a new portlet called WCT Place Holder becomes available. One or more copies of this placeholder portlet are used on the pages representing applications. In portal terminology, the copy of the portlet is known as a "concrete portlet instance." Each placeholder portlet is configured with the necessary parameters to represent a view in the application.
A special page resides on the portal with a unique name lwp.WorkPlaceRCPPages. The pages on the server that represent client applications are all created as child pages of the lwp.WorkPlaceRCPPages page. The default location for lwp.WorkPlaceRCPPages is at the portal server root page level.
You must now make a copy of the placeholder portlet (this copy is referred to as a "concrete" copy) and add the parameters that describe the attributes of corresponding views in the Managed Client (size, location, and so on). Although most of the RCPML manifest file is generated from the parameters contained in the portlet, the provisioning page itself also has some important parameters, for example the appearance of the icon in the switcher bar (see the previous section). The Managed Client also uses the title for the provisioning page as the application title that will appear under the icon in the client application switcher bar.
NOTE: Initially, the new page and newly created concrete portlet can’t be accessed by non-administrators, so you need to modify the access for both page and portlets to allow users access to the page. For example, you can add "all authenticated portal users" in the member list of user role. (Refer to the WebSphere Portal administration documentation for information on setting access control on pages.) Also, remember to select Support RCPML in Advanced options when you create the page.
The following is a list of the parameters that must be configured for each copy of the placeholder portlet:
-
rcpView is the view id in plugin.xml.
-
ratio is the size of the view.
-
id.Feature_x is the feature id for the feature containing the view.
-
version.Feature_x is the version of the feature required.
-
match.Feature_x defines the compatibility of the portlet.
-
visible controls the visibility of the view.
For example, the completed portlet setup might resemble the following:
Figure 7. Portlet setup
Refer to the WebSphere Portal administration documentation for information on copying and configuring portlets. For convenience, we provide an XML access script that can be used with the portal XML access facility to create a page containing a new copy of the placeholder portlet with configured parameters.
Next, run the XMLAccess facility on the Workplace server. This allows you to run a script remotely against the server. In our case, we will run a script that will make a concrete portlet of the placeholder portlet containing required parameters, put it onto a provisioning page, and set the access control for both the page and portlet. (For more information about XMLAccess, see the WebSphere Portal InfoCenter.) The code for the complete sample script is contained in this sidefile.
There’s a few things to note about the script code. The create-oids="true" option specified in the request element of the script instructs the server to generate new objectid values for each resource that is created by the script, thus creating new resources rather than overwriting existing ones (unless a uniquename is also specified that matches an existing resource uniquename on the server). When a matching uniquename already exists, the server resource is updated rather than a new resource being created.
Uniquename is the user-specified identifier for each resource. This raises the possibility of a naming collision. When this happens, XMLAccess will simply overwrite all resources without asking. So you need to be careful about the uniquename. You can use the following simple XMLAccess script to export everything under the RCP rootpage, and check for naming collisions:
<?xml version="1.0" encoding="UTF-8"?>
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd" type="export"
transaction-level="none">
<portal action="locate">
<content-node action="export" uniquename="lwp.WorkPlaceRCPPages"
export-descendants="true"/>
</portal>
</request>
|
The output contains the applications that come with the provisioning component, so when you're ready for more complex applications, the output file provides a good example.
If you want to run XMLAccess scripts from a client machine, you need to copy the tools.jar file from <LWP Server install direction>\PortalServer\bin. This makes it available to the JVM on the client. Then run the command line:
javaw -classpath tools.jar com.ibm.wps.xmlaccess.XmlAccess -in
<your_script_name> -out <output_script_name> -user <User_Name>
-pwd <Password> -url <Your_Server_address(IP)> :9081/lwp/config
|
This command line applies to Windows; running on other platforms is similar.
The <output_script_name> setting is the output from XMLAccess. It is an XMLAccess script and can also work as an input script, for example, when you export a file from the server, you can use the output file to restore it or copy it to another server. In this case, our script is an update operation, and the output file will do nothing more than show the result. You can expect to see a status element such as <status element="all" result="ok"/> to indicate everything is running properly. The operation details are recorded in the XML comments at the beginning of the output file. Bear in mind that you need to have the Administrator role for the virtual resource Portal to use XMLAccess facility.
Conclusion
Now it’s the time to check the result. Download and run the Managed Client from your Workplace server. You should see something similar to the following:
Figure 8. Sample Workplace Managed Client page
Notice the bright green "Hi" icon at the bottom of the left navigator. This represents our sample application that has been successfully deployed to the Managed Client using our automatic deployment system. This is a very simple application that consists of little more than an icon and a view. However, it's sufficient to demonstrate how you can deploy your own applications and other updates with this deployment system.
In this article, we explained the basic procedure for setting up a system for automatically deploying updates to Workplace Managed Client users. We described the two main steps involved: setting up an update site in Eclipse and creating a provisioning page in Workplace. You can follow our examples to set up your own application, to help you manage and control the update and deployment processes as your Workplace community expands and grows.
Resources
About the author  | | | Hangsu Ma works in the IBM Dublin Software Lab. He is also an Undead Warcraft III TFT player, who recently reached level 26 on the battle.net. You can contact Hangsu at hangsuma@ie.ibm.com. |
Rate this page
| 
