IBM WebSphere Portal Notifications

Overview

Portal Notifications for IBM WebSphere Portal allows authenticated portal users to View and Send Messages to other users of the same Portal. E-mail notifications are sent to the personal email account of the recipient, along with an announcement to indicate the arrival of a new message.

• The solution installer is used to install all Portal Notifications parts.
• Portal Notifications supports Derby and IBM DB2 database.
• The main user interface is built using the following portlets: Secure Message portlet and Tag Cloud portlet.
• Individual message are presented to users with the IBM Lotus Web Content Management Access builder, which uses Web Content Management Presentation templates.
• Messages are created with the IBM Lotus Web Content Management Authoring portlet.
• IBM Lotus Web Content Management is used as main message repository and a secondary 'Message Headers' database to store message header information.
• IBM Lotus Web Content Management Libraries included with Portal Notifications:
• Resource library: authoring and presentation template, etc.
• Content library : Site, site area and user messages(when created)
• XML Access scripts are used to define pages for the solution installer and DB scripts define database tables.

Overview of the user interface

The Portal Notifications User interface has the following characteristics:

• A Combination of WPF and Web Content Management portlets
• Two main screen areas: navigation area and content area

Navigation area includes Folder links

• Inbox
• Sent. Click on link to see list of messages

Content area:

• The remainder of the page is used for the main presentation area (content area). It displays the following:
• List of messages (e.g. Click on “inbox” in the navigation and content area will list all inbox messages
• Message content (click on one of the listed messages and see the message content)

User interface features

New

Creates new message
When the user clicks on 'New' it pop up a 'lightbox' for composing the message where they can enter the subject, recipient(s) and message details.
When the user clicks 'Save and close'(send) - Message is stored in Web Content Management and the Associated Web Content Management workflow publishes the content and also copies message header information into the 'Message Headers' Database . One copy for each sender, recipient or copy for each user assigned to a group recipient.
When the user clicks 'Close'(cancel) - Message is not stored in Web Content Management and no header information is stored in 'Message Headers' Database

Reply

Reply to Selected single message
When the user clicks on 'Reply' it pop up a 'lightbox' with prepopulated subject and recipient .Subject with have 'Re' appended to the front of the old subject if it not already there

Refresh

Refresh message list
Refresh the content area with an updated list of messages for the currently selected “tag” (e.g. Inbox, Sent )

Delete

Delete selected message(s)
Select one or more messages and click 'delete' button,
For each selected message, the Message Header entry for the current user(owner) is deleted from the 'Message Header' database
For each selected message, if there are no other owners of the associated Web Content Management content (this message is not in any other users Inbox, Sent folder, etc.), the associated Web
Content Management content is also deleted

More Action

Mark selected messages(s) as read or unread
Select one or more messages (check boxes) Click “More Actions” button and select “Mark Unread” from the list
For each selected message, the Message Header entry for the current user (owner) is updated in the “Message Header” database (set to “Unread”)
Web Content Management content is unaffected
Similarly when select 'Mark read' , the Message Header entry for the current user (owner) is updated in the “Message Header” database (set to “read”)

Features

Custom recipient picker

The custom recipient picker displays a restricted list of users and groups that a secure message may be sent to. It replaces the standard person picker widget.
The widget show a list of user and groups when the user hovers over the widget or focuses on the widget.
The following screen shots show how users and group are displayed:

Configuring the custom recipient picker

The "Secure Message" authoring template has a test element called "customRecipient". The element uses custom JSP to create the custom recipient widget. The Custom JSP field must be set to /tbmesg_wcm;/jsp/recipientPicker.jsp. This is the context root and location of the custom jsp page.
The custom jsp uses an interface and java beans found in project tbmesg_wcm at com.ibm.accelerators.securemsg.picker. Our implementation of that interface is found at com.ibm.accelerators.securemsg.picker.impl.RecipientListImpl.java.

Administering the custom recipient picker

For each user that uses the custom recipient picker the administrator must create a group name equal to the user's UID. For example user bzechman will have a corresponding group with cn equals bzechman. The admin should add all users and/or groups to this group that will be available to the user. E.g. add user doctorXX to group bzechman. Add group support to group bzechman.
 

E-Mail notifications

When a user sends a message the receiver of that message will get an email notification to say that the message has arrived. The message will contain the sender's name, the subject and a link to the secure message.
To prevent email notifications from becoming spam like, there are some rules to reduce the amount of emails sent as follows:

• If a single user or set of single users are selected then an email will be sent to those users.
• If a group has been selected then the system will check how many members are in the group.
• The system uses two parameters to filter groups, the "Groups size limit" parameter and a "Group includes list".
• If the group size in under the group size limit then an email notification is sent to each member.
• If the group size is over the group size limit then the system checks the group includes list.
• If the group is in the group includes list then an email is sent to each member of the group.
• If the group is not in the group includes list then an email is not sent to the group but an email is sent to the sender to say that a notification email has not been sent to that group.

Configuring e-mail notifications

Each email notification contains a link to the Secure Messaging inbox. This link is gotten from a properties file and added to the secure messaging content (template) as a hidden field when the content is created. The "Secure Message" authoring template contains a text element called "secureMsgLink". The configuration of this link is contained in tbmesg_wcm.war at com.ibm.accelerators.securemsg.doclink.config.properties.

• The group includes list is a Portal group. The name of the group is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties.
• The group size limit is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties.
• The email text is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties.
• The email is sent using a WAS mail session object. The jndi name of the mail session object is set in tbmesg_data.war at com.ibm.accelerators.securemsg.email.config.properties.
• The Lotus Web Content Management workflow action called Send Message Email Action is added to the workflow stage Publish Stage to execute the email sending code when the secure message content has been created.

Administering e-mail notifications

The install should create the 'group includes list' group. The administrator should add groups to this list that are over the group size limit but still want email notifications sent to them.

PUMA utility classes

The Custom Recipient Picker and the Email Notifications features use PUMA to retrieve user data from Portal. The utility class can be found in project tbmesg_wcm at com.ibm.accelerators.securemsg.puma. The classes are packaged in the build in tbmesg_dataEAR.ear/tbmesg_shared.jar/com/ibm/accelerators/securemsg/puma

This folder contains pumaAttributes.properties file that contains a mapping of PUMA properties files. These properties must be set to comply with the installed system PUMA attributes. The properties are as follows:

• PumaUtil.user.unique.id=uid
• PumaUtil.user.full.name=cn
• PumaUtil.user.email=ibm-primaryEmail
• PumaUtil.group.id=cn

Out of scope

• No message attachments, print, export
• No message archiving
• No records management (e.g. Stored for compliance)
• Not an e-mail system
• No built-in workflow
• No user defined address book

Limitations

The information in this topic provides details about some of the limitations and anomalies that you may encounter when using the tool:

• When sending message to group , users added to the group after the message has been sent will not receive the message.
• Time stamp displayed in all the messages show only the server Timezone even when the user are in different timezone
• When there are less than 5 messages, Clicking the show 'All' will cause a 'page 2' link to show up even though there is only 1 page. This problem has been fixed in WebSphere Portlet Factory version 7.0.

Installing with the solution installer

To install Portal Notifications, you can use the solution installer for WebSphere Portal. Download the solution installer from the Portal catalog at: https://greenhouse.lotus.com/plugins/plugincatalog.nsf/assetDetails.xsp?action=editDocument&documentId=3E21DDAB3EE4DC598525775E00576826

Notes:

• DB2 - Create database 'tbmesg' and connect to the database
• Derby - Database 'tbmesg' is created automatically by the installer

To install Solution Installer you will need to copy the Solution Installer files to the PortalServer directory and then register them with the ConfigEngine. The required steps involved are as follows:

1. Extract the SolutionInstaller.zip file to a temporary directory. For example: C:\temp\.

2. Copy the SolutionInstaller directory that contains the component and documentation directories, which is extracted from the .zip file, to the PortalServer directory.

3. Open a command line prompt and go to the ConfigEngine directory, for example: C:\IBM\WebSphere\wp_profile\ConfigEngine

4. Type the following command to register Solution Installer with ConfigEngine:

ConfigEngine.bat -install -assemblyRoot /SolutionInstaller -installPath -user -pwd -hostname
-port -offeringName PortalServer -assemblyName SolutionInstaller -expandBinaries false

Parameters in between <> signs must be replaced with specific information relating to your system. For example,

Windows: ConfigEngine.bat -install -assemblyRoot
c:/WebSphere/PortalServer/SolutionInstaller -installPath c:/WebSphere/PortalServer -user wpsadmin -pwd wpsadmin -hostname localhost.servername.com -port 10033
-offeringName PortalServer -assemblyName SolutionInstaller -expandBinaries false

Note: You can verify that the command has completed successfully by checking registry.xml for 'SolutionInstaller' in the ConfigEngine folder.

5. Type the following command to set up the PAA offering directory and register it with the ConfigEngine:

Windows: ConfigEngine.bat si-setup
Linux: ./ConfigEngine.sh si-setup

Notes:

• You will need to add wasPassword and PortalAdminPwd in wkplc.properties file in ConfigEngine/properties folder.
• You can verify that the command completed successfully by checking that the paa folder is created in directory, for example: C:\IBM\WebSphere\paa.
  

6. Select the paa file according to the target Portal server and database system. There are four paa files: securemsg_db2_p615.paa, securemsg_derby_p615.paa, securemsg_db2_p7.paa, securemsg_derby_p7.paa.

7. To install PAA file to WebSphere Portal, enter the following: ConfigEngine.bat install-paa -DPAALocation=
8. After installing PAA, edit the SecureMessaging.properties file (Websphere/Paa/SecureMessaging/components/SecureMessaging)and enter the values as per your configuration eg. edit dbUserName and dbPassword

9. Deploy PAA content to WebSphere Portal:

Windows: ConfigEngine.bat deploy-paa -DappName=PaaAssemblyname eg. ConfigEngine.bat deploy-paa -DappName=SecureMessaging
Linux: ./ConfigEngine.sh deploy-paa -DappName=PaaAssemblyname

10. Restart the portal server.

11. Check that the protocol for the Mail sessions object is the one for your mail server in the Integrated Solutions Console (Resources -> Mail -> Mail sessions). You may need to change from smtps to smtp.

Uninstalling

To uninstall PAA run the command ConfigEngine.bat remove-paa -DappName=SecureMessaging

Note: Uninstalling removes all the messages from the database.

Manual Installation

Unzip the file securemsg-db2.paa (for IBM DB2) or securemsg-derby.paa (for Derby) using the command  jar -xvf (run the command at \java\bin directory)

Installing Lotus Web Content Management Libraries

Portal Notifications includes two Web Content Management libraries that must be installed:

• Secure_Messaging_Resources - includes authoring and presentation templates, and other related components
• Secure_Messaging_Content - includes Site and Site area (this is where users' message content is stored)

To install, import both of these Lotus Web Content Management libraries by following the instructions provided in the WebSphere Portal Information Center (See Exporting and Importing WCM Libraries).

1. Update the was_profile_root/PortalServer/wcm/config/wcm60_cfg.xml file on the server. Confirm that the following properties in the init section are set as specified, modifying the properties if necessary:

• ExportDir: This is the directory on the source server where the exported data will be written.
• ImportDir: This is the directory from where the exported data will be read when importing the data to the target server. If exporting and importing across a network, this can be the same directory as the one specified in "ExportDir". Otherwise, you must copy the exported data from the "ExportDir" to the "ImportDir" before running the import task in step 4.
• SourceServerPort: The host name and port for the source server. By default, the port is 10040.
• TargetServerPort: The host name and port for the target server. By default, the port is 10040.
• ExportUserId: If the source administrator is not the default (wpsadmin), set this value to the source administrator short name.
• ExportPassword: Set this value to the source administrator password.
• ImportUserId: If the target administrator is not the default (wpsadmin), set this value to the target administrator short name.
• ImportPassword: Set this value to the target administrator password.
• WebLib: The name of the Web content library to transfer. If exporting multiple libraries enter each library name separated by a comma. For example,
• WebLibProperty: Set the value for this property to icm:title.

2. Import the Web content library to the target server.

a. Open a command prompt on the target server.
b. Run the import-wcm-data task from the wp_profile_root/ConfigEngine directory.
• Windows: ConfigEngine.bat import-wcm-data -DPortalAdminPwd=password -DWasPassword=password
• UNIX: ./ConfigEngine.sh import-wcm-data -DPortalAdminPwd=password -DWasPassword=password
• i5/OS: ConfigEngine.sh -profileName profile_root import-wcm-data -DPortalAdminPwd=password -DWasPassword=password
where profile_root is the name of the IBM WebSphere Application Server profile where WebSphere Portal is installed; for example, wp_profile.
c. Verify that this transfer step completed without errors. If any errors occurred, check the portal logs on the target server for extended diagnostic information.

3. Reset the Web content event log.

4. Restart the server.

The secureMsgLib directory contains both libraries. Portal must be restarted after this step, or you can wait and do it after the "Define WAS Data Source" step (see below). In the case of a software upgrade (installing a new version of Portal Notifications), use the Portal Administration console to delete these 2 libraries before importing the libraries again.

Creating a database for IBM DB2

To support DBCS characters create a Unicode database, using the command DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY territoryname (to support DBCS Characters), you must specify 'tbmesg' for the database name.

Windows
1. Open a DB2 Command Prompt
2. Create database
3. Connect to 4) Before running the script uncomment all the line needed for manual installation and then
4. run the ddl script to create tables (run the command from the directory where ddl script is stored). For example, db2 -tvf create_tables_db2.ddl

Linux
1. Open the terminal
2. login as db2 instance userid eg. su db2inst1
3. To create tables - same steps as in windows

Creating a database for Derby

To create database in Derby, do the following:

1. Go to \derby\bin\embedded\ij.bat
2. Create database in wp_profile_root\PortalServer\derby. For example, run the following commands:

ij> connect 'jdbc:derby:;create=true;user=;password=';
connect to database
ij> connect 'jdbc:derby:;
run the script to create tables
ij> run '< script file>'; eg. ij>run 'create_tables_derby.sql';
ij> exit;

Defining a data source

1. JDBC Provider and Datasource settings. Make sure that:

• In Provider Verify that environment variables used in the Class Path are also defined, e.g. DB2UNIVERSAL_JDBC_DRIVER_PATH; this can be checked on WAS console Environment -> WebSphere Variables. For example, E:/IBM/SQLLIB/JAVA (i.e. should point to directory with db2jcc.jar etc.)
• In Data source Verify that the Component-managed authentication alias has been defined (this must specify the user id and password of the database)

2. Stop and restart Portal.

Configuring a mail session object

To send notification mail to users personal email, configure Mail Session Object in WebSphere Application Server as follows:
1. Log in to the administrative console.
2. Select Resources -> Mail -> Mail Session -> Create New Mail Session
3. Select WebSphere_Portal scope
4. Give any Name and for JNDI name enter mail/secureMessaging
5. Enter all the details.

Installing the portlet application

Use Portal Admistration to:

• Install tbmesg_portlets.war (Portlet Administration -> Web Modules)
• Execute (import) SecureMessagingPages.xml to define pages( Portal Settings -Import XML)

Installing the EAR

Use the WebSphere Application Server Administration console to deploy tbmesg_dataEAR.ear (resource collection and Web Content Management custom workflow action) as described here:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/topic/com.ibm.wp.ent.doc_v615/wcm/wcm_dev_class_register_workflow.html

Installing Lotus Web Content Management Authoring Custom JSP

1. Copy secureMsgLaunchPageWithReturn.jsp into the installed Lotus Web Content Management Authoring portlet WAR directory. Target directory has the following format:
wp_profile_directory/installedApps/cell/PA_wcm_AuthoringUI.ear/ilwwcm-authoring.war/jsp/html/

Note: A delay of up to 10 seconds may be required in order for the new JSP file to be recognized by the Lotus Web Content Management authoring portlet.

The group includes list 'secureMessageIncludes' is a Portal group. The name of the group is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties.

The group size limit is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties. you can change the limit here

The email text is set in tbmesg_data.war at com.ibm.accelerators.securemsg.workflowaction.sendEmailNotificationConfig.properties.

Can add the server name here C:\WebSphere\wp_profile\installedApps\dubxp\tbmesg_dataEAR.ear.ear\tbmesg_wcm.war\WEB-INF\classes\com\ibm\accelerators\securemsg\doclink