Managing the Instant Messaging Portal Archive

The following topics describe using the Instant Messaging Portal Archive:

• Instant Messaging Portal Archive Overview

• Enabling and Disabling the Portal Archive Provider

• Configuring the Instant Messaging Portal Archive Provider

• Managing Archived Data in the Portal Server Search Database

• Changing the Display of Archived Data

• Sample Deployment Scenario for Archive Provider

Instant Messaging Portal Archive Overview

Features of the Instant Messaging Portal Archive Provider include the following:

• It captures all the Instant Messaging traffic passing through the server.

• The archived data can be stored under separate categories in the Portal Server Search. Storing the data as separate categories helps in simplifying the search and retrieval of the archived data. The search can be performed using the Portal Server desktop.

• The security feature of Portal Server Search can be used to provide an access control list. The archive provider provides security features by which only a set of administrative users can be allowed to access the archived data.

• The data can be managed using the Portal Server Search database management tools.

All instant messages are divided into the following categories for the purpose of archiving:

Chat - All messages in the private conference rooms.

Conference - All messages in the public conference rooms.

Alerts - All alert messages.

Poll - All poll messages.

News - All messages posted in the news channels.

The Instant Messaging Portal Archive contains the following components:

Archive and Retrieval Component - Portal Server Search component, also known as the Archive and Retrieval component, is used to store archived Instant Messages. The Instant Messaging archive data is indexed and can be stored in the Portal Server Search database. You can also assign categories to the archive data. For example, you can store alert messages under the Alert category. Storing data in separate categories helps to simplify search operations and enables quick retrieval of archived data.

Instant Messaging Archive Search or Display Servlet - When the end user performs a search operation for documents matching certain criteria, the Portal Server Search fetches pages matching this criteria. These pages can be remote web pages or Instant Messaging archive data, also referred as Instant Messaging resource descriptors.

• For remote web pages, the URL of the pages matching the criteria is listed in the Search Results List. When the end user clicks the URL of a web page in the Search Results List, the browser fetches this page from the remote web container.

• For Instant Messaging Resource Descriptors, the archive data is stored in the Portal Server Search database and is not available as downloadable documents from the web container.

  When the end user clicks the URL of the Instant Messaging resource descriptors to view the archive data, the Instant Messaging Archive Search or Display servlet is invoked. The Instant Messaging Archive Search servlet retrieves the information from the Portal Server Search database and generates a text or HTML response containing the Instant Messaging Archive data.

Instant Messaging Archive Provider - This component is invoked by the Instant Messaging server whenever instant messages are to be archived. The Instant Messaging Archive Provider builds the Summary Object Interchange Format (SOIF) compliant Resource Descriptors (RD) based on the data provided by the Instant Messaging server. The Archive Provider uses Portal Server Search APIs to send these Resource Descriptors to the Portal Server Search database, and maintains a buffer of the records to be submitted to the Portal ServerSearch database to reduce the performance hit.

Figure 18–1 illustrates Instant Messaging Portal Archive components.

Figure 18–1 Instant Messaging Portal Archive Components

Enabling and Disabling the Portal Archive Provider

You enable the Instant Messaging Archive Provider or your custom archive provider by modifying parameters in iim.conf.

To Enable the Instant Messaging Portal Archive Provider

Before You Begin

Ensure that you have enabled archiving for Instant Messaging as described in To Enable Instant Messaging Archiving.

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Add a line to iim.conf for the type of archive provider you want to enable.

   For a custom archive provider, add the following line:

   iim_server.msg_archive.provider = provider-name

   To use the Portal Server Search-based Archive Provider, replace provider- name with the following:

   com.iplanet.im.server.IMPSArchive

   The iim_server.msg_archive.provider parameter contains a comma-separated list of archive providers. If you want to enable the Portal archive in addition to the email archive for example, the parameter and its value should be entered as follows:

   iim_server.msg_archive.provider = com.iplanet.im.server.IMPSArchive, \ com.iplanet.im.server.EmailIMArchive

3. If you are running Sun Java^TM System Portal Server 7 2006Q1 or later, provide a value for the following parameter:

   iim_arch.portal.search="Portal Server Search URL"

   Where Portal Server Search URL is the Search URL for the Portal Server. For example:

   iim_arch.portal.search="http://portal.siroe.com:8080/search1/search"

4. Save and close iim.conf.

5. Refresh the Instant Messaging server configuration.

   imadmin refresh

6. Log in to psconsole as amadmin.

   For instructions, refer to the Portal Server documentation.

7. Select Manage Channels and Containers.

8. Select the portal and organization that will host the search function.

9. Select IMChannel from the DP XML Tree View.

10. Enter the search server URL as the value for “searchServer”.

    For example:

    http://portal.siroe.com:8080/search1/search

11. Save properties.

To Disable the Portal Archive Provider

1. Open iim.conf.

   See iim.conf File Syntax for more information.

2. Delete the com.iplanet.im.server.IMPSIMArchive value from the iim_server.msg_archive.provider parameter.

3. Save and close iim.conf.

4. Refresh the Instant Messaging server configuration.

   imadmin refresh

Configuring the Instant Messaging Portal Archive Provider

The Instant Messaging Archive Provider stores the archived messages as resource descriptors (RD) in the Portal Server Search database. The archive provider uses the following fields of the Portal Server Search schema:

Title - This field contains the names of the public conference rooms for Conference category, names of the participants in a chat session for the Chat category, subject of the Alert messages, and the names of the News Channels for alerts and news categories. The title field will contain “Poll from Sender” for the poll category, where Sender represents the display name of the sender of the poll.

Keyword - For conference and chat categories, this field contains a list of all the participants in the conference room. For a public conference room, it also contains the name of the conference room. For the Alert category, it contains the display names of the sender and the recipients. For the News category, it contains the name of the channel. For the Polls category, it contains the list of sender and recipients. For all categories, in addition to the above values this field also contains a unique ID for the categories.

Table 18–2 shows the unique ID and gives a description for each category in the archive provider.

ReadACL - For the Conference and News categories, the value for this field is taken from the access control files of the respective conference rooms and news channels. For the Chat category, this field contains the DN of the participants. For the Alert category, this field contains the sender’s DN and the recipient’s DN. For the Poll category, the archive provides a new access control file.

The search access to the RDs is controlled by the value in the ReadACL field. If the document level security is enabled, the end user has access to the search results only if the ReadACL field has the end user’s DN.

Description - This field contains the archived message without the HTML formatting.

Full-Text - This field contains the HTML formatted archived messages.

Classification - This field contains the category of the archived message.

To Configure the Archive Provider

1. Open iim.conf.

   See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying iim.conf.

2. Add or edit the archive provider configuration parameters as desired.

   See Table A–8 for a list of parameters you can modify.

3. Save and close iim.conf.

4. Refresh the Instant Messaging server.

To Store Archived Messages in a Non-default Database

Use this procedure to configure Instant Messaging to store archived messages in a database other than the default.

1. Open iim.conf.

   See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying iim.conf.

2. For the default archive provider, add the following line:

   iim_arch.portal.search.database = database-name

   where database-name is the name of your non-default database.

3. Save and close iim.conf.

4. Modify the Portal Server Search Channel.

   Change the Portal Server Search Channel to add an option for searching the data in another database. See the Sun Java System Portal Server Desktop Customization Guide for more information.

5. Change to the IMProvider directory.

   For example:

   cd /etc/opt/SUNWps/desktop/default_locale/IMProvider/

   Where locale is the locale of the language used in your deployment. For example, default_ja or en_US. Also, if you created multiple instances of Instant Messaging, the name of the /default directory will vary depending on the instance.

6. Create a back up of the IMArchiveDisplay.jsp file.

7. Open the IMArchiveDisplay.jsp file.

8. Search through the IMArchiveDisplay.jsp file and locate the following two lines of code:

   <search:setQuery query = "<%= scope %>"/> <search:setRDMType rdmType = "rd-request"/>

9. Between the two lines of code shown in the previous step, add the following line of code:

   <search:setDatabase database = "database-name"/>

   After you add the new line of code, that section of code should look as follows:

   <search:setQuery query = "<%= scope %>"/> <search:setDatabase database = "database-name"/> <search:setRDMType rdmType = "rd-request"/>

   where database-name is the name of the non-default database.

10. Replace the virtual search server with the physical server hostname.

11. Save and close IMArchiveDisplay.jsp.

Managing Archived Data in the Portal Server Search Database

These instructions are Solaris-specific.

The Instant Messaging data is archived in the form of Resource Descriptors (RDs) in the Portal Server Search database. The individual entries in the Portal Server Search database are called resource descriptors (RDs). An RD is a specific set of information about a single resource. The fields of each RD are determined by the Portal Server Search database schema.

To manage the archived data, you need to manage the Resource Descriptors (RDs) in the Portal Server Search database. This section explains some of the frequently performed Portal Server Search database maintenance tasks.

For more information on managing data in the Portal Server Search database, see the Sun Java System Portal Server Administration Guide.

rdmgr Command

The rdmgr command is the main command used to work with the Search service. It gives the administrator two types of subcommands: one that is used to work with resource descriptors (RDs), and another used for database maintenance. The rdmgr command is normally run in a search-enabled Portal Server instance directory.

To Invoke the rdmgr Command

1. Change to the https-servername directory.

   cd /var/opt/SUNWps/https-servername

   Where servername is the name of the Portal Server

2. Type the following at the command-line:

   run-cs-cli portal-svr-base/SUNWps/bin/rdmgr options

   where portal-svr-base is the directory in which Portal Server is installed.

   For more information on rdmgr command, see Command-Line Utilities in Sun Java System Portal Server Administration Guide.

Searching Resource Descriptors

Running rdmgr command with the argument value -Q generates a list of resource descriptors (RDs) that refines the search operation.

For example:

• To search for resource descriptors (RDs) containing the text testing, type:

  run-cs-cli portal-svr-base/SUNWps/bin/rdmgr -Q testing

• To search for resource descriptors (RDs) belonging to a particular category, type the following command. Enter the command as a single line:

  run-cs-cli portal-svr-base/SUNWps/bin/rdmgr -Q "classification=Archive:Chat:January"

Deleting Resource Descriptors

The following are the examples for deleting resource descriptors (RDs) from the Portal Server Search database:

To delete all resource descriptors (RD) containing the text testing, type:

run-cs-cli portal-svr-base/SUNWps/bin/rdmgr -d -Q testing

To delete all resource descriptors (RD) from a category Archive:Chat:January, type the following command. Enter the command as a single line:

run-cs-cli portal-svr-base/SUNWps/bin/rdmgr
-d -Q "classification=Archive:Chat:January"

Changing the Display of Archived Data

The data that is archived is deployed using the IMArchiveDisplay.jsp file. The IMArchiveDisplay.jsp file is installed in the folder /etc/opt/SUNWps/desktop/default/IMProvider by default. You can modify this file to change the style and the resource strings of the archived data.

For example, you can replace the default system message displayed when an end user joins the room as described in the following steps.

Similarly, the resource strings for the other keys and the style for displaying the key information can also be modified.

If you change the attribute name of Title and Full-Text in the default schema of the Portal Server Search is changed, then these changes should also be reflected in the IMArchiveDisplay.jsp file.

To Modify the Default System Message

1. Edit IMArchiveDisplay.jsp.

2. Search for the following the code lines in IMArchiveDisplay.jsp:

   .... ht.put("has_joined_the_room","<span class='user'> {0} </span> <span class='headervalue'> has joined the room.</span>"); ....

3. Replace the headervalue with the desired text.

   For example:

   .... ht.put("has_joined_the_room","<span class='user'> {0} </span> <span class='headervalue'> has entered the room.</span>"); ....

Sample Deployment Scenario for Archive Provider

This sample deployment scenario explains how to archive the related Instant Messaging data collectively.

Example 18–1 Archiving Related Instant Messaging Data Collectively

Create separate categories for each type of data. For example, in the Archive category where all the archived Instant Messaging data are stored, create a subcategory called “Chat” for storing chat messages. You can also create subcategories for archiving data based on time. For example, to archive chat data for the month of December 2002 the subcategory will be:

Archive:Chat:2002:12

To Archive All Instant Messaging Chat Data Based on Time

1. Change to theim-cfg-base directory.

   See Instant Messaging Server Directory Structure for information on locating im-cfg-base.

2. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

3. Add the following value for iim_arch.chat.categoryname:

   iim_arch.chat.categoryname = Archive:Chat:%Y:%M

   The archive provider automatically assigns the current year for %Y and current month for %M. These values are taken from the system date and time.

To Archive and Back up Instant Messaging Chat Data for the Month of December 2005 to the Subcategory

1. Type the following:

   rdmgr -Q "classification=Archive:Chat:2005:12" > archive.soif

2. Copy the archive.soif file to your backup system.

To Remove Archived Instant Messaging Chat Data for the Month of December 2005 from the Portal Server Search Database

1. Type the following at the command line:

   rdmgr -d "classification=Archive:Chat:2005:12"