| Sun ONE Instant Messaging Administrator's Guide |
Chapter 5
Managing The Instant Messaging ArchiveThis chapter explains how to manage and configure the Sun ONE Instant Messaging Archive.
This chapter contains the following sections:
Instant Messaging Archive OverviewThe Instant Messaging archive captures instant messages and archives these messages in a Portal Server Search database. It enables the 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 6.0 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. When the 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.
- For the remote web pages, the URL of the pages matching the criteria is listed in the Search Results List. When the user clicks the URL of a web page in the Search Results List, the browser fetches this page from the remote web server.
- For the Instant Messaging Resource Descriptor, the archive data is stored in the Portal Server Search database and is not available as downloadable documents from the web server.
When the user clicks the URL of the Instant Messaging resource descriptors to view the archive data, the Instant Messaging Archive Search or Display JSP is invoked. The Instant Messaging Archive Search JSP 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 Submit Servlet. Sun ONE Portal Server Search 6.0 does not provide a method for adding records to the Portal Server Search database from a remote server. A command-line utility rdmgr is used to add new records to the Portal Server Search database. The Instant Messaging Archive Submit Servlet enables addition of records to the Portal Server Search database from a remote Instant Messaging server.
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 sends these Resource Descriptors to the Instant Messaging Archive Submit servlet for them to be added to the 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 user to set default archive options, such as “archive all conferences”, and change the default on a per-transaction basis. For example, the user can choose not to archive the content of the conferences.
Figure 5-1 illustrates Sun ONE Instant Messaging Archive components.
Figure 5-1 Sun ONE Instant Messaging Archive components
Archiving Instant MessagesAll 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:
- It captures all the Instant Messaging traffic passing through the server.
- The archived data can be stored under separate categories on 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 admin users can be allowed to access the archived data.
- The data can be managed using the Portal Server Search database management tools.
Enabling the Archive ProviderTo enable archive provider in Instant Messaging:
- Change to the Config directory. For example, on Solaris:
cd /etc/opt/SUNWiim/default/config
- Open the iim.conf file.
For example:
vi iim.conf
- Add the following line to the iim.conf file:
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
It is adequate to perform the above steps to enable the archive provider in Instant Messaging, provided the messenger archive control is enabled. Refer to the section on Enabling Instant Messenger Archive Control for further details.
If the messenger archive control is disabled, it is possible to enable archiving by setting the following option:
iim_server.msg_archive.auto = true
This setting directs the server to ignore the end-user’s archive control settings.
By default this setting is not added by the installer during the install. This is done on purpose, to avoid archiving data by mistake before completing the archive setup. The administrator needs to add this setting to ignore the end user’s archive control settings.
- Save the file.
- Refresh the Instant Messaging server configuration. To refresh type:
imadmin refresh
Sun ONE Instant Messaging provide 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 ProviderThe 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 poll category, where $Sender is 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 for each category and their description
ReadACL. For the Conference and News categories, the value for this field is taken from the ACL 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 ACL file.
The search access to the RDs is controlled by the value in the ReadACL field. If the document level security is enabled, the user has access to the search results only if the ReadACL field has the user’s DN. If the Instant Messenger Archive control is enabled, for the chat messages, the user DN added to the ReadACL field depends on the 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
The Archive Provider configuration parameters need to be manually added to the iim.conf file in the directory /etc/opt/SUNWiim/default/config.
The following are the optional Archive Provider configuration parameters which can be added to the iim.conf file:
Managing Archived Data in the Portal Server Search Database
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 6.0 Administrator’s Guide at:
http://docs.sun.com/source/816-6359-10/
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:
For more information on rdmgr command, see Command-Line Utilities in Sun ONE Portal Server 6.0 Administrator’s Guide at:
http://docs.sun.com/source/816-6359-10/cliadm.html#19141
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 $portalbasedir/SUNWps/bin/rdmgr -d -Q testing
To delete all resource descriptors (RD) from a category Archive:Chat:January, type:
Enabling Instant Messenger Archive ControlThe Instant Messenger Archive Control component enables the end user to control the archived instant messages. This component allows the 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 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 Messager 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 standalone 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:
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:
Changing the Display of the Archived DataThe 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 a user joins the room “joe has joined the room” to “joe has entered the room;” perform the following:
- Edit the IMArchiveDisplay.jsp file. For example:
vi IMArchiveDisplay.jsp
- Replace the code line in Code Example 5-1 with Code Example 5-2 in the file IMArchiveDisplay.jsp:
Code Example 5-1 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-2 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.
How to Use CGI Script to Submit the DataThe Submit servlet uses the Runtime.exec() method of Java to submit the data to the Portal Server Search database. When the Portal Server is under a high load this operation might take a long time. To avoid this delay you need to configure the Instant Messaging server to use CGI script for submitting the data to the Portal Server search database.
To configure the Instant Messaging server to use CGI script to submit the data:
- Copy the CGI script IMArchiveSubmit.cgi from /etc/opt/SUNWps/desktop/default/IMProvider/ to the appropriate directory in your Web Server instance.
- Configure the Web Server to run the IMArchiveSubmit.cgi script.
For more information on configuring the Web Server to the CGI script, see Sun ONE Web Server, Enterprise Edition Administrator's Guide at:
http://docs.sun.com/source/816-5691-10/esprgrm.htm#21236
- Add the following parameter iim_arch.submit_cgi in the iim.conf file.
Where:
$URL_OF_THE CGI_SCRIPT is the URL of the CGI script.
Sample Deployment Scenario for Archive ProviderThis 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 archive 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:
- Change to the config directory. For example, on Solaris type:
cd /etc/opt/SUNWiim/default/config
- Edit the iim.conf file. For example:
vi iim.conf
- Add the following value for the parameter 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 the chat data the month of December 2002 to the subcategory, type:
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"
