Sun logo      Previous      Contents      Index      Next     

Sun ONE Instant Messaging 6.1

Chapter 5
Managing The Instant Messaging Archive

This chapter explains how to manage and configure the Sun ONE Instant Messaging Archive.

This chapter contains the following sections:

Instant Messaging Archive Overview

The Instant Messaging archive captures instant messages and archives these messages in a Portal Server Search database. It enables the end user to query and retrieve these archived messages using the Search page on the Portal Server desktop.

Sun ONE Instant Messaging Archive contains the following components:

Archive and Retrieval Component. Sun ONE Portal Server Search component also known as Archive and Retrieval component is used to store the archived Instant Messages. The Instant Messaging archive data is indexed and can be assigned to categories and stored in the Portal Server Search database. For example, alert messages can be stored under the Alert category.

Note

Storing data in separate categories helps in simplifying the search operation and enables quick retrieval of the 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 they could be Instant Messaging archive data also referred as Instant Messaging resource descriptors.

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) complaint Resource Descriptors (RD) based on the data provided by the Instant Messaging server. It uses Portal Server Search APIs to send these Resource Descriptors to Portal Server Search database. It also maintains a buffer of the records to be submitted to the Portal Server Search database, to reduce the performance hit.

Instant Messenger Archive Control. Instant Messaging data can be archived automatically without any interaction from the end user. To control the archive functionality the end user needs to enable the Instant Messenger Archive Control component. This component allows the end user to set default archive options, such as “archive all conferences”, and change the default on a per-transaction basis. For example, the end user can choose not to archive the content of the conferences.

Figure 5-1 illustrates Sun ONE Instant Messaging Archive components.

Figure 5-1  

This figure shows Sun ONE Instant Messaging archive components and data flow.

Sun ONE Instant Messaging Archive Components

Archiving Instant Messages

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

Chat. All the messages in the private conference rooms.

Conference. All the messages in the public conference rooms.

Alerts. This category contains all the alert messages.

Poll. This category contains all poll messages.

News. This category contains all messages posted in the news channels.

The following are the features of Sun ONE Instant Messaging Archive Provider:

Enabling the Archive Provider

To enable archive provider in Instant Messaging:

  1. Change to the config directory. For example, on Solaris:

    2. cd /etc/opt/SUNWiim/default/config

  2. Open the iim.conf file.

    3. For example:

    vi iim.conf

  3. Add the following line to the iim.conf file:

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

    iim_server.msg_archive = true

    For a custom archive provider, add the following line:

    iim_server.msg_archive.provider = provider_name

    To use the Portal Server Search based archive, replace the provider_ name with the following:

    com.iplanet.im.server.IMPSArchive

  4. Save the file.
  5. Refresh the Instant Messaging server configuration. To refresh type:

    6. imadmin refresh

Sun ONE Instant Messaging server provides the APIs and SPIs that can be used to write custom archive providers. For more information on Instant Messaging APIs, see "Instant Messaging APIs".

Configuring the Archive Provider

The 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 will contain a list of all the participants in the conference room. For a public conference room, it will also contain the name of the conference room. For the Alert category, it will contain the display names of the sender and the recipients. For the News category, it will contain the name of the channel. For the Polls category, it will contain 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 5-1 shows the unique ID and gives a description for each category in the archive provider.

Table 5-1  Unique ID for each category and their description

Category

Unique ID

Conference

Chat

RoomName-StartTime

Where:

RoomName - Name of the public or private conference room

StartTime - Is the timestamp of the creation of RD

Alert

Alert-messageID

Where:

messageID - Message Id of the message which will be archived. Message Id has importance when the RD contains only one message. For example, News message and Alert message.

Poll

Poll-pollID

News

TopicName-messageID

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 archiver will provide 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. If the Instant Messenger Archive control is enabled, for the chat messages, the end user DN added to the ReadACL field depends on the end-user selection.

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.

Archive Provider Configuration Parameters

Table 5-2 lists and describes the archive provider configuration parameters that can be added to the iim.conf file:

Table 5-2  Archive Provider parameters added to the iim.conf file.

Parameter

Default Value

Description

iim_arch.title.attr

Title

This parameter contains the name of the field equivalent to the Title field in the default schema of the Portal Server Search.

iim_arch.keyword.attr

Keyword

This parameter contains the name of the field equivalent to the Keyword field in the default schema of the Portal Server Search.

iim_arch.readacl.attr

ReadACL

This parameter contains the name of the field equivalent to the ReadACL field in the default schema of the Portal Server Search.

iim_arch.description.attr

Description

This parameter contains the name of the field equivalent to the Description field in the default schema of the Portal Server Search.

iim_arch.fulltext.attr

Full-Text

This parameter contains the name of the field equivalent to the Full-Text field in the default schema of the Portal Server Search.

iim_arch.category.attr

Category

This parameter contains the name of the field equivalent to the Category field in the default schema of the Portal Server Search.

iim_arch.readacl.admin

None

This parameter contains the administrator’s DN. Multiple values should be separated by “;”

iim_arch.readacl.adminonly

false

This parameter will contain true or false.

true - Only the administrator’s DN specified by the parameter iim_arch.readacl.admin will be added to the ReadACL field overwriting the default behavior of the ReadACL field.

false - The administrator’s DN specified by the parameter iim_arch.readacl.admin will be added to the ReadACL field in addition to the default behaviour.

iim_arch.categories

all

This parameter contains a list of message types that can be archived.

The value can be:

poll

alert

chat

conference

news

Multiple values can be specified separated by commas(“,”).

iim_arch.categoryname

None

If a category name is not assigned for any of the categories then the value of this parameter is taken as the category name.

iim_arch.alert.categoryname

None

This parameter contains the name of the category containing the archived alert messages.

Note: It is not required to dedicate a category to alert messages.

iim_arch.poll.categoryname

None

This parameter contains the name of the category containing the archived poll messages.

Note: It is not required to dedicate a category to poll messages.

iim_arch.conference.categoryname

None

This parameter contains the name of the category containing the archived conference messages.

Note: It is not required to dedicate a category to conference messages.

iim_arch.chat.categoryname

Name

This parameter contains the name of the category containing the archived chat messages.

Note: It is not required to dedicate a category to chat messages.

iim_arch.news.categoryname

None

This parameter contains the name of the category containing the archived news messages.

Note: It is not required to dedicate a category to news messages.

iim_arch.conference.quiettime

5

This parameter contains the maximum duration of silence between two consecutive messages in a room (both public and private) after which the RD expires and a new RD is created for archiving the message. The value is in minutes.

iim_arch.poll.maxwaittime

15

This parameter contains the (maximum) time for which poll data is buffered in the server. The value is in minutes.

iim_arch.ignoreexplicitdeny

true

This parameter will contain true or false.

true - For Poll and Conference category the data with explicit deny access will not be archived. Each time when these messages are not archived this information will be logged into the server.log file.

false - For Poll and Conference category the data with explicit deny access will not be archived and the message will be added to the Portal Server Search database.

Note: If you do not explicitly deny access to a room or a news channel then the default access is either READ or WRITE or MANAGE. Some end users can also be granted NONE access.

iim_arch.portal.search

None

The value of the this parameter should be the URL of the Portal Server Search servlet. For example: http://www.example.com/portal/search

If this parameter is not present then the Archive Provider determines the value of the Portal Server Search URL based on the AMConfig.properties file present on the system.

iim_arch.portal.admindn

None

The value of this parameter should be the dn of the admin user. For example: uid=amadmin,ou=People,o=internet

This parameter is required when the Document level Security in the Portal Search Server is on.

iim_arch.portal.adminpassword

None

The value of this parameter should be the password of the admin user as specified by the iim_arch.portal.admindn parameter.

This parameter is required when the Document level Security in the Portal Search Server is on.

iim_arch.portal.search.database

None

The value of this parameter should be the name of the database where Sun ONE Instant Messaging server stores archived messages. If this parameter is not defined then all messages are stored in the default database of Sun ONE Portal Server Search.

iim_arch.portal.deployuri

 

/portal

This parameter contains the deploy URI of the Portal Server.

iim_arch.portal.channelname

 

IMChannel

 

This parameter contains the name of the Instant Messaging Channel.

Storing Sun ONE Instant Messaging Archived Messages in a non-default database

To store Sun ONE Instant Messaging archived messages in a non-default Portal Server Search database instead of a default database, follow these steps:

  1. Modifying the iim.conf file
    1. Change to the config directory. For example, on Solaris:

      2. cd /etc/opt/SUNWiim/default/config

    2. Open the iim.conf file using an editor of your choice.

      3. For example, you could type:

      vi iim.conf

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

      4. iim_arch.portal.search.database = database-name

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

    4. Save the file.
  2. 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 ONE Portal Server Desktop Customization Guide for more information.

  1. Modify the IMArchiveDisplay.jsp file:
    1. Change to the following directory:

      2. /etc/opt/SUNWps/desktop/default/IMProvider/

    2. Create a back up of the IMArchiveDisplay.jsp file.
    3. Edit the IMArchiveDisplay.jsp file with an editor of your choice. For example, you could type the following:

      4. vi IMArchiveDisplay.jsp

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

      5. Code Example 5-1  Search Code from IMArchiveDisplay.jsp File, Before Editing

      <search:setQuery query = "<%= scope %>"/>

      <search:setRDMType rdmType = "rd-request"/>

    5. Between the two lines of code shown in Code Example 5-1, add the following line of code:

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

      After you add the new line of code, that section of code should look like Code Example 5-2:

Code Example 5-2  Search Code from IMArchiveDisplay.jsp File, After Editing

<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.

Managing Archived Data in the Portal Server Search Database

Note

These instructions are Solaris specific as Sun ONE Portal Server is supported on Solaris only.

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 maintenance tasks on the Portal Server Search database.

For more information on managing data in the Portal Server Search database, see the Sun ONE Portal Server Administrator’s 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 the other that is 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 following directory:

    2. cd /var/opt/SUNWps/https-servername/

  2. Type the following in the command-line:

    3. run-cs-cli portal-server-install-dir/SUNWps/bin/rdmgr args

    where portal-server-install-dir is the directory in which Portal Server is installed.

For more information on rdmgr command, see Command-Line Utilities in Sun ONE Portal Server Administrator’s Guide.

Searching Resource Descriptors (RD)

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

For example:

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-server-install-dir/SUNWps/bin/rdmgr -d -Q testing

To delete all resource descriptors (RD) from a category Archive:Chat:January, type:

run-cs-cli portal-server-install-dir/SUNWps/bin/rdmgr -d -Q "classification=Archive:Chat:January"

Enabling Instant Messenger Archive Control

The Instant Messenger Archive Control component enables the end user to control the archived instant messages. This component allows the end user to search for the archived instant messages stored in the Portal Server Search database by clicking the Archive button in the Instant Messenger main window. It also enables the end user to set default archive options, such as “archive all conferences” in the Archive tab of the Instant Messenger. The Instant Messenger Archive Control feature is provided by two optional Instant Messenger modules.

The Instant Messenger Archive Control component can be enabled by setting the archive_control applet parameter in the applet descriptor file.

The applet descriptor files for the Instant Messaging LDAP deployment that need to be changed are:

Changes for JNLP files and jnlpLaunch.jsp files:

If you are using Java Web Start to launch the Instant Messenger, perform the following steps to enable the Instant Messenger Archive Control feature in the Instant Messenger:

  1. Go to the Instant Messenger documentation root directory to locate the im.jnlp and imssl.jnlp files

    2. The jnlpLaunch.jsp file can be found at:

    /etc/opt/SUNWps/desktop/default/IMProvider

  2. Edit the jnlp or jsp file, and add or edit the following line:

    3. <argument>archive_control=true</argument>

Changes for html applet pages and pluginLaunch.jsp files:

If you are using Java Plug-in to launch the Instant Messenger, perform the following steps to enable the Instant Messenger Archive Control feature in the Instant Messenger:

  1. Go to the messenger documentation root directory to locate the im.jnlp and imssl.jnlp files

    2. The jnlpLaunch.jsp file can be found at:

    /etc/opt/SUNWps/desktop/default/IMProvider

  2. Edit the jnlp or jsp file, and add or edit the following line:

    <PARAM NAME="archive_control" VALUE="true" />

    <EMBED archive_control=true;/>

    3. Note

    Instant Messenger Archive Control should not be enabled if the value of iim_server.msg_archive.auto is set to true in the iim.conf file of the Instant Messaging Server, as end users’ messenger settings will not have any effect.

Changing the Display of the 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. The file can be modified to change the style and the resource strings of the archived data.

For example, to replace the default system message displayed when an end user joins the room “joe has joined the room” to “joe has entered the room;” perform the following:

  1. Edit the IMArchiveDisplay.jsp file with an editor of your choice. For example, you could type the following:

    2. vi IMArchiveDisplay.jsp

  2. Replace the code line in Code Example 5-3 with Code Example 5-4 in the file IMArchiveDisplay.jsp:

    3. Code Example 5-3  Modifying the default system message.

    ....

    ht.put("has_joined_the_room","<span class='user'> {0} </span>

    <span class='headervalue'> has joined the room.</span>");

    ....

    Code Example 5-4  After replacing the default system message.

    ....

    ht.put("has_joined_the_room","<span class='user'> {0} </span>

    <span class='headervalue'> has entered the room.</span>");

    ....

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

If 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.

Sample Deployment Scenario for Archive Provider

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

To archive the 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 sub- category 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 the chat data based on time, do the following:

  1. Change to the config directory. For example, on Solaris type:

    2. cd /etc/opt/SUNWiim/default/config

  2. Edit the iim.conf file. For example:

    3. vi iim.conf

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

    4. 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 the chat data the month of December 2002 to the subcategory, type:

  1. rdmgr -Q "classification=Archive:Chat:2002:12" > archive.soif
  2. Store the .soif file to your backup system.

To remove the archived chat data for the month of December 2002 from the Portal Server Search database, type:

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



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.