2009
© Copyright International Business
Machines Corporation 2009. All rights reserved.
Abstract: This article shows
how to configure and use a portlet plug-in for users to access IBM Lotus
Connections 2.x from the IBM WebSphere Portal side. The plug-in changes
from dojo 0.4 to dojo 1.1.1 compared with Lotus Connections 1.0.
Contents
1 Overview of the portlet plug-in
2 Architecture
3 How the portlet plug-in works
4 Prepare the environment to install
the plug-in
5 Install and configure the plug-in
6 Features provided by the plug-in
6.1 Tags
7 Troubleshooting
8 About the authors
1 Overview of the portlet plug-in
The Lotus Connections 2.0 portlet plug-in
brings the capability of Lotus Connections to WebSphere Portal. Unlike
the 1.0 version, portlet plug-in 2.0 is installed on WebSphere Portal 6.1,
and it updates from using dojo 0.4 to dojo 1.1.1.
This portlet plug-in provides views of five
main Lotus Connections 2.0 features—Activities, Blogs, Communities, Dogear,
and Profiles—with the following functions:
· Multiple
views in each application
· Display
tag clouds
· Support
search and customized views
Users can read and search the contents of
Lotus Connections 2.0 features through this portlet plug-in. All the provided
functions are based on the complete, correct configuration, and the new
features in this release are as follows:
· The
dojo version is upgraded from 0.4.2 to 1.1.1, in line with the dojo version
being used in WebSphere Portal 6.1.
· Added
SiteMinder support.
· Added
IBM Group2 languages support (supporting 24 languages in total: French,
German, Spanish, Italian, Portuguese, Traditional Chinese, Simplified Chinese,
Korean, Japanese, Arabic, Czech, Danish, Dutch, Finnish, Greek, Hebrew,
Hungarian, Norwegian, Polish, Portuguese, Russian, Swedish, Turkish, English).
· Added
WebSphere Portal 6.1 support.
2 Architecture
Figure 1 shows an example architecture of
one customer’s deployment environment. They have a portlet installed on
a WebSphere Portal cluster, with the portlet sending HTTP request to get
the Feed of the feature content.
Figure 1. Example architecture
The WebSphere Portal cluster and Lotus Connections
cluster are behind the WebSeal (see figure 2). They all enable Single Sign
On (SSO) with the Tivoli Directory Server. The personalize mode does
not need to be specified because SSO can help the portlet get all the user
information with the log-in authentication.
Figure 2. WebSphere Portal and Lotus Connections
clusters
3 How the portlet plug-in works
The Lotus Connections portlet provides views
of five Lotus Connections 2.0 features: Activities, Blogs, Communities,
Dogear, and Profiles. Each of the five Lotus Connections services has its
own application programming interfaces (APIs) to read and update the existing
feature information.
The APIs for Lotus Connections are accessed
through HTTP, so it works from any program that can send and receive HTTP.
Lotus Connections APIs use the Atom Syndication Format to provide XML data
information. The program can use the APIs to send and receive the Feed
of XML format data through HTTP.
To display applications in the portlet, portlet
Java™ sources initialize the NLV messages, collect all the configurations,
and then pass this information to the dojo functions in JSP files. Using
this information, the dojo functions make up the HTTP API format and send
out requests through proxy servlets.
The Lotus Connections APIs provide Feed of
data in XML format. Dojo functions get XML data and parse the XML. The
dojo functions make up the JSP code, according to the content from XML,
and update the code to JSP pages. After this event, JSP pages refresh themselves
and display the features in the application.
Each time you change to another application,
the actions described above are executed to refresh the page. So
the communication between the portlet and Lotus Connections mainly relies
on using a dojo function to send a request and get the Feed of XML data.
For more information about the Lotus Connections
APIs, refer to the
Lotus Connections 2 information center.
4 Prepare the environment to install the
plug-in
You have the option to enable SSO between
a Lotus Connections feature and a WebSphere Portal Server configured for
stand-alone LDAP. SSO is not required for portlet plug-in, but it’s highly
recommended. With SSO, users can access all their content after they log
in to WebSphere Portal server once. Without SSO, the user needs to put
credentials into the Personalize mode.
SSO is required only if email can't be used
as the Login attribute due to corporate policy. As of the Lotus Connections
2.0 release, email is required when calling to retrieve Dogear and Blogs
feeds. Setting up SSO can by-pass such a limitation; however, you cannot
enable SSO between WebSphere Portal server and Lotus Connections if they
use different LDAPs or the WebSphere Portal Server does not use LDAP for
authentication. In that case, a user must input their email address in
the Personalize mode for Blogs.
For detailed steps to configure single sign-on
(SSO), refer to the information center topic Installing
the Lotus Connections Portlet.
If you use HTTPS to access your Lotus Connections
server, you must import SSL keys into your WebSphere Portal 6.1 server.
(This helps the WebSphere Portal server pass the SSL certification when
it sends a request to the Lotus Connections server.) To import SSL keys,
follow these steps.
1. Navigate
to the Profiles feature URL to get the certification file, for example:
https://www.company.com/profiles.
Prepare to export the SSL keys from the
browser.
2. View
the certification of this Web site ; the browser will display a message
dialog for the Certificate view (see figure 3). Open the Details tab, and
then click the button “Copy to File…”.
Figure 3. Certificate view
3. In
the Certificate Export Wizard (see figure 4), select the option “Base-64
encoded X.509 (.CER)” and click Next.
Figure 4. Certificate Export Wizard dialog
4. Before
exporting the file, you need to create the folder “ \certifications”
in which to save your exported SSL keys. Type in your certification file
name and click Next (see figure 5). The certification file is then saved
in the \certifications directory.
Figure 5. Specify file name
5. Open
the Admin Console page of WebSphere Portal server 6.1 from this URL: https://yourHostName:port/ibm/console,
to prepare to import the SSL keys into
WebSphere Portal server.
6. In
the left-hand pane of the Admin Console page, navigate into Security >
SSL certificate and key management > Key stores and certificates >
NodeDefaultTrustStore > Signer certificates. Click the Add button.
7. A page
similar to that shown in figure 6 displays. Input your certification name
in the Alias field and the key location in the File name field. You can
use the WebSphere Application Server variables in your location.
Figure 6. SSL certificate and key management
For Profiles, you can input "Profiles"
for the Alias and input the right path of the profiles.cert: ${WAS_INSTALL_ROOT}/certification/profiles.cert.
Since “${WAS_INSTALL_ROOT}” is a WebSphere Application Server variable,
its value is the full path of the WebSphere Application Server.
8. Repeat
steps 1 through 7 for any other features that use HTTPs.
9. Finally,
restart WebSphere Portal server to put your changes into effect.
5 Install and configure the plug-in
1. Go
to the IBM
Lotus Business Solutions Catalog
Web site and download the IBM Lotus Connections Multi-Service Portlet 2.0
for Portal 6.1. After you finish downloading the package, you will get
a zip file. Unzip it and get the package named “snor.portlet.war”.
2. Deploy
the Lotus Connections application to the WebSphere Portal server:
a. Navigate
to: http://:10038/wps/portal
and log in as Portal administrator.
b. Click
“Launch”, and on the drop-down list, select “Administration”.
c. On
the Administration page, navigate to WebModule and click the Install button
to set up the Lotus Connections .war file
d. On
the next install page, select the snor.porlet.war that you will deploy
to the WebSphere Portal server, via the Browse button.
e. Click
Finish to complete the installation; you will see that the file “snor.portlet.war”
has been installed.
3. Create
a page to view Lotus Connections 2.0 on WebSphere Portal server:
a. Navigate
to Launch > Manage Pages; click “Content Root”.
b. On
the next page, click “Home”.
c. On
the Home page, click “New Page”.
d. Input
a Title like “Lotus Connections 2.0” for the new page and keep other
setting as default.
e. Navigate
to “Launch Home”, a new page “Lotus Connections 2.0” is created.
f. Click
“New Page” to create a new sub-page to for Lotus Connections under the
created page (see figure 7).
Figure 7. Create a new page
g. On
the next page, input a title for the new page and keep the other settings
as default. Click Ok.
h. Click
the “Add portlets” button to add portlets for this page.
i. Search
portlets by the keywords “Lotus Connections”, select the “Lotus Connections”
portlet, and click OK (see figure 8).
Figure 8. Create Lotus Connections portlet
j. The
portlet has been added successfully (see figure 9). Click Done.
Figure 9.
4. Configure
and Personalize:
a. Navigate
to the page shown in figure 10. On the drop-down list, click “Configure”.
Figure 10. Configure
b. On
the Configuration page (see figure 11), configure Lotus Connections for
the portlet; click Save. (Note that “https” is usually used here.)
Figure 11. Configuration page
c. Select
one component of Lotus Connections and make a customized setting via the
Personalize page. In this case, we use the Dogear component (see figure
12).
Figure 12. Personalize Dogear
d. Customize
your settings and click Save (see figure 13).
Figure 13. Customize settings
5. Map
Security roles to users/groups:
a. Navigate
to the Portal Admin console page and log in as administrator.
b. Navigate
to Applications > Enterprise Applications, and select the Lotus Connections
application (see figure 14).
Figure 14. Enterprise Applications page
c. In
the next panel, select “Map security roles to users/groups” (see figure
15).
Figure 15. Map security roles to users/groups
d. Map
the roles as shown in figure 16.
Figure 16. Map the roles
e. Save
the changes and restart the Lotus Connections application.
6 Features provided by the plug-in
The portlet brings the social networking
capabilities of Lotus Connections to WebSphere Portal, providing the following
components:
· Activities.
Collaboration tool for collecting, organizing, sharing, and reusing work
that is related to a project goal.
· Blogs.
Online journals that you can use to deliver timely information with a personal
touch.
· Communities.
A Web site that you create so that people who share a common interest can
interact with one another and share resources.
· Dogear.
Social bookmarking tool that you can use to save, organize, and share
Internet and intranet bookmarks (see figure 17).
· Profiles.
Directory of the people in your organization that includes the information
you need to form and encourage effective networks.
Figure 17. Dogear component in WebSphere
Portal
Functionally, the portlet provides a search
feature, and the ability to customize views (see figure 18). You can switch
to different components to view corresponding content, and in each component
you can also switch between views. The view options include all views provided
by each component in Lotus Connections and the customized views:
· Activities.
By default, “My Activities”, “Completed,” and “To do” views.
· Blogs.
By default, “All Blogs” and “My Blogs” views.
· Communities.
By default, “All Communities” and “My Communities” views.
· Dogear.
By default, “All Bookmarks”, “Popular Bookmarks”, “My Bookmarks,”
and “My Watchlist” views.
· Profiles.
The search view is displayed.
Figure 18. Portlet functions
Also, via the portlet menu “Edit Shared
Settings”, you can customize your own view (see figure 19). Here you can
use the Create custom search query and Add to List options so that a customized
view will be listed and can be checked to view by the customer.
Figure 19. Customize a view
As shown in the above figure, select the
· “Display
portlet contents as search results” check box, if you want the Lotus Connections
portlet to function as a search portlet.
NOTE: If there are no search results to display,
only the title of the feature will display in the portlet. If this checkbox
is checked, the portlet's main view will only display search results, and
the tag cloud and search bar will be removed from the main view.
You can create a custom search view and set
this view as the default view. And you can only see the search result if
you check the “Display portlet contents as search results”
· “Show
the application” check box, if you want this feature to be available from
the portlet.
· Check
boxes beside the views you want to enable for the feature. The views you
select here will be available from the view drop-down list for the feature.
Note, however, that the Create custom search, Create custom tag filter,
and fields will not display when you select the Profiles view:
· Create
custom search query: Provide “Search for” and “Query name” values
· Create
custom tag filter: Provide “Search for” and “Filter name” values
· Show
the following as default view: Choose the view that should be displayed
when the feature is first accessed.
6.1 Tags
A tag is a descriptive keyword that you can
assign to a profile, bookmark, activity, activity entry, or blog to help
classify it. A tag cloud is a collection of the tags used by everyone in
an organization. Popular tags in the tag cloud display in a larger, bold
font.
On the top right corner of the main view,
click Tags. (You can click Hide Tags to stop the tag cloud from displaying.)
If you want the tag cloud to display by default when you open the feature,
choose Personalize from the Portlet menu, and then select the Display tags
check box (see figure 20).
To display all entries that are tagged with
a specific tag term in the current view, click a tag in the cloud. Via
the portlet menu “Personalize view”, you can specify “If display tags
by default”, “How to Open links”, “How many entries to show per page”,
and “Whose data to display”.
Figure 20.
· Display
tags: Select this check box to set tag cloud to be displayed by default.
Note: This check box is not displayed when
you are editing the view associated with Profiles.
· Open
links in: Select how to open links, on new window or the same window.
· Number
of entries: Select a number from the box to specify how many entries to
show per page
· User
ID and Password: Type the user ID and password you use for Lotus Connections.
· Should
profile list results be displayed in portlet: Select this check box to
indicate that the list results should be displayed in the portlet.
Note: This check box is only displayed when
you are editing the view associated with Profiles.
7 Troubleshooting
In this section we describe some issues that
you may encounter:
1. "No
entries are available" under My Bookmarks of the Dogear component.
This issue is caused by a special configuration
for Dogear.
To resolve: Make sure the Login properties
of Lotus Connections is "mail". Log into the WebSphere Application
Server admin console and configure the "Login properties" as
"mail" via Security > Secure administration, application,
and infrastructure > Single sign-on (SSO) > Trust association >
Federated repositories > . Also, you need
to configure the UserID and PWD as mail on the Configure view on the WebSphere
Portal server.
2. Javascript
Error: “An error occurred processing the request. HTTP request status
was: 500”
This occurs because you did not import the
SSL certification into the WebSphere Portal server.
To resolve: Enable SSO and use the
HTTP instead of HTTPS. Or, you can import the correct SSL certifications.
See the InfoCenter topic “Prepare the environment to install the plug-in”.
3. Javascript
Error: “Your Lotus Connections username and password were not accepted.
Go to the Personalize mode to update your username and password.”
To resolve: After you ensure that
your user credentials are correct, verify that proxy security roles are
mapped properly.
4. If
SiteMinder is used as secure solution software, in order to ensure Blogs
work correctly, you must make sure that email is set as the Login attribute
on WebSphere Portal, on the SiteMinder Policy server, and on Lotus Connections.
For more details on configuring Blogs with SiteMinder as a secure solution
software, refer to the InfoCenter topic, “Enabling
single sign-on for SiteMinder”.
5. For
error messages generated by the IBM Lotus Connections Multi-Service Portlet,
search the SystemOut.log of WebSphere Portal for the included codes to
identify problems and find their solutions:
| CLFNF6001E: Could not store portlet preferences.
| The portlet failed to save preferences to
portal preferences store. It may be caused by incorrect permission settings
granted by the administrator.
| Check if the user has permission to store
preferences.
|
| CLFNF6002E: Error storing slot id.
| The portlet failed to store user credentials
in the portal credential vault.
| Check your portal credential vault configuration.
|
| CLFNF6003E: There was an error with a name.
| Caused by: javax.naming.
NamingException when the portlet is trying
to lookup Portal services (i.e. Puma service or Identification service).
| Check your portal configuration to make sure
Puma services and Portal Identification service are available.
|
| CLFNF6004E: JSONTranslator could not modify
portlet preferences.
| The portlet failed to save preferences to
portal preferences store. It may be caused by incorrect permission settings
granted by the administrator.
| Check if the user has permission to store
preferences.
|
| CLFNF6005E: There was an error with the portlet
service.
| The server encountered an error when using
Portal Puma services.
| Check your portal configuration to make sure
puma services function correctly.
|
| CLFNF6006E: Error creating credential.
| The portlet failed to create a private credential
slot.
| Check your portal credential vault configuration.
|
| CLFNF6007E: Name not found.
| The portlet failed to locate portal services.
(i.e. Puma or Identification)
| Check your portal configuration to make sure
puma services and Portal Identification are available.
|
| CLFNF6008E: There was an error serializing
an id.
| The portlet failed to serialize portlet window
ID.
| Reinstall the portlet instance on the page,
if the problem is consistent, check your portal configuration.
|
| CLFNF6009E: Could not get custom views.
| The portlet failed to change the value for
a read-only preference attribute.
| Check if the user has permission to store
preferences.
|
| CLFNF6010E: Query was stored in a bad format:
{0}.
| The user used the character “|” in a custom
search query or in a custom tag filter.
| Do not use “|” in a custom search query
or in a custom tag filter.
|
| CLFNF6011E: Error getting user credentials.
| The portlet encountered an error when attempting
to retrieve user credentials from the Portal credential vault.
| Check the portal credential vault configuration. |
8 About the authors
Peng Zhang is a software engineer
on the Lotus Connections Install team at the IBM China Software Development
Lab.
Liang Yang is a tester on the Software
Verification Test (SVT) team for Lotus Connections at the IBM China Software
Development Lab.
Xin Xu is a tester within SVT team
of Lotus Connections at the IBM China Software Development Lab.
|
|
|
|
| Version 2 |
March 10, 2009 |
6:00:52 PM |
by Amanda J Bauman  |
|
|