test

Sun Java System Instant Messaging 7.2 Administration Guide

Chapter 18 Managing Archiving for Instant Messaging

This chapter explains how to configure and manage email, Portal, and custom archiving for Instant Messaging in the following sections:

Archiving Overview

You can archive instant messages in the following ways:

You can configure Instant Messaging to use one or more archive methods at the same time.

Enabling and Disabling Archiving for Instant Messaging

Regardless of whether you choose to use portal, email, a custom archive, or any combination of archives, you enable the archiving capability in Instant Messaging the same way as described in this section. Disabling archiving as described in this section disables all archives.

ProcedureTo Enable Instant Messaging Archiving

After you enable archiving for Instant Messaging, you need to enable the archive provider for the type of archive you want to use as described in the following sections:

  1. Open iim.conf.

    See iim.conf File Syntax for information.

  2. Add the following line to iim.conf if it does not already exist.


    iim_server.msg_archive = true

  3. Save and close iim.conf.

  4. Refresh the server.


    imadmin refresh server

ProcedureTo Disable Instant Messaging Archiving

This procedure disables all archiving for Instant Messaging. If you want to disable only email archiving, Portal archiving, or a custom archive you have configured, see one of the following sections:

  1. Open iim.conf.

    See iim.conf File Syntax for information.

  2. Set the iim_server.msg_archive parameter to false.


    iim_server.msg_archive = false

  3. Save and close iim.conf.

  4. Refresh the server.


    imadmin refresh server

Managing the Instant Messaging Email Archive

You can use Instant Messaging to archive poll, chat, conference, news channel, and alert content and email that content to end-users and administrators. You can use any email client to search and manage the archived content. This section describes the Instant Messaging email archive in the following sections:

The Instant Messaging server caches archived records until they are emailed. If you enable email archiving, the memory requirements for the server increase. See the Sun Java Communications Suite 5 Deployment Planning Guide for information on performance tuning.

Enabling and Disabling the Instant Messaging Email Archive Provider

You enable or disable the email archive provider by modifying a parameter value in iim.conf.

ProcedureTo Enable the Instant Messaging Email Archive

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

  2. Add the following line to iim.conf if it does not already exist.


    iim_server.msg_archive.provider = com.iplanet.im.server.EmailIMArchive

    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. Save and close iim.conf.

  4. Refresh the Instant Messaging server configuration. 


    imadmin refresh

ProcedureTo Disable the Instant Messaging Email Archive Provider

  1. Open iim.conf.

    See iim.conf File Syntax for more information.

  2. Delete the com.iplanet.im.server.EmailIMArchive 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 Email Archive Settings

You can configure which administrators will receive emails containing archived instant messages. You can configure a separate list of administrators to receive polls, news, conference, alerts, or chat sessions. You can also configure Instant Messaging to use the extended RFC 822 header. Doing so allows mail clients to filter messages based on the header content.

Note –

If you run configure after modifying these parameters for the email archive, any values you input will be overwritten.

Table 18–1 describes the configuration parameters you use to define which administrators will receive email archives, as well as whether or not to use the extended RFC 822 header, and the content of that header.

Table 18–1 Email Archive Configuration Parameters

Parameter 

Default Value 

Description 

iim_arch.admin.email

Empty String 

Comma-separated list of administrator email addresses. 

iim_arch.alert.admin.email

None 

Comma-separated list of administrator email addresses to which all archived alert messages will be sent. This parameter overrides iim_arch.admin.email for alert messages.

iim_arch.chat.admin.email

None 

Comma-separated list of administrator email addresses to which all archived chat messages will be sent. This parameter overrides iim_arch.admin.email for chat messages.

iim_arch.conference.admin.email

None 

Comma-separated list of administrator email addresses to which all archived conference messages will be sent. This parameter overrides iim_arch.admin.email for conference messages.

iim_arch.poll.admin.email

None 

Comma-separated list of administrator email addresses to which all archived poll messages will be sent. This parameter overrides iim_arch.admin.email for poll messages.

iim_arch.news.admin.email

None 

Comma-separated list of administrator email addresses to which all archived news messages will be sent. This parameter overrides iim_arch.admin.email for news messages.

iim_arch.email.archiveheader.name

None 

Name of the extended RFC 822 header. 

iim_arch.email.archiveheader.value

all 

Value corresponding to the header name for iim_arch.email.archiveheader.name.

ProcedureTo Configure Administrator Recipients and the RFC 822 Header Format for the Instant Messaging Email Archive

  1. Open iim.conf.

    See iim.conf File Syntax for more information.

  2. Add the parameters in Table 18–1 and appropriate values to iim.conf.

  3. Refresh the server.


    imadmin refresh

Email Header Format

The RFC 822 header content for email messages containing various types of archived Instant Messaging content is described in the following sections:

RFC 822 Email Archive Header Fields for One to One Chat

From:

Chat session initiator.

To:

Receiver and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Chat session initiator.

Subject:

First useful message over 50 characters in length.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider based on the message thread.

RFC 822 Email Archive Header Fields for Private Conferences

From:

Chat session initiator.

To:

Other participants and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Chat session initiator.

Subject:

If a subject is set for the conference, the conference subject is used. If no subject is set, first useful message over 50 characters in length is used.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider based on the conference ID.

RFC 822 Email Archive Header Fields for Public Conferences

From:

Room owner in archive data.

To:

Associated mailing list, users with explicit access to the conference room, and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Not used.

Subject:

[Conference name] subject.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider based on the conference ID.

RFC 822 Email Archive Header Fields for Poll Questions with Replies

From:

Poll sender.

To:

Poll sender and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Not used.

Subject:

Poll question.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider.

RFC 822 Email Archive Header Fields for Poll Replies Only

From:

Poll sender.

To:

Poll recipients and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Poll sender.

Subject:

Poll question.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider.

RFC 822 Email Archive Header Fields for Alerts

From:

Alert sender.

To:

Alert recipients and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Not used.

Subject:

Alert subject.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider.

RFC 822 Email Archive Header Fields for News Channel Posts

From:

News channel post sender.

To:

Mailing list associated with the news channel and any administrators configured in iim.conf. See Table 18–1 for more information.

Cc:

Not used.

Subject:

News channel post subject.

Date:

Creation date of the email message by the archive provider.

Reply-to:

Not used.

X-XMPP-Message-ID

Generated by the email archive provider based on the news channel ID.

Managing the Instant Messaging Portal Archive

The following topics describe using the Instant Messaging Portal Archive:

Instant Messaging Portal Archive Overview

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

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.

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

This figure shows Instant Messaging Portal archive components and data flow.

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.

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

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

Table 18–2 Unique ID and Description for Archive Provider Categories

Category  

Unique ID  

Conference 

Chat 

RoomName-StartTime

Where: 

RoomName - Name of the public or private conference room

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

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

ProcedureTo 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

Note –

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.

ProcedureTo 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:

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.

ProcedureTo 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

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

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

ProcedureTo 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"

Using a Custom Archive Provider

In addition to the Portal and email archives, you can choose to use a custom archive provider.

ProcedureTo Enable a Custom 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. Save and close iim.conf.

  4. Refresh the Instant Messaging server configuration. 


    imadmin refresh

ProcedureTo Disable a Custom Archive Provider

  1. Open iim.conf.

    See iim.conf File Syntax for more information.

  2. Delete only the value for the custom archive provider from the iim_server.msg_archive.provider parameter.

  3. Save and close iim.conf.

  4. Refresh the Instant Messaging server configuration.


    imadmin refresh