Sun Java System Instant Messaging 7 2005Q1 Administration Guide |
Chapter 7
Managing The Instant Messaging ArchiveThis chapter explains how to manage and configure the 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 end user to query and retrieve these archived messages using the Search page on the Portal Server desktop.
Instant Messaging Archive contains the following components:
Archive and Retrieval Component. 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.
- For the 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 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 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) 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 7-1 illustrates Instant Messaging Archive components.
Figure 7-1 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 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
- Save the file.
- Refresh the Instant Messaging server configuration. To refresh type:
imadmin refresh
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 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 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 7-1 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 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 7-2 lists and describes the archive provider configuration parameters that can be added to the iim.conf file:
Storing Archived Messages in a Non-default Portal Server Search Database
To Store Archived Messages in a Non-default Database
- Modify the iim.conf file.
- Change to the config directory. For example, on Solaris:
cd /etc/opt/SUNWiim/default/config
- Open the iim.conf file using an editor of your choice.
For example, you could type:
vi iim.conf
- 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.
- Save the file.
- 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.
- Modify the IMArchiveDisplay.jsp file:
- Change to the following directory:
/etc/opt/SUNWps/desktop/default/IMProvider/
- Create a back up of the IMArchiveDisplay.jsp file.
- Edit the IMArchiveDisplay.jsp file with an editor of your choice. For example, you could type the following:
vi IMArchiveDisplay.jsp
- Search through the IMArchiveDisplay.jsp file and locate the following two lines of code:
Code Example 7-1 Search Code from IMArchiveDisplay.jsp File, Before Editing
<search:setQuery query = "<%= scope %>"/>
<search:setRDMType rdmType = "rd-request"/>
- Between the two lines of code shown in Code Example 7-1, 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 like Code Example 7-2:
where database-name is the name of the non-default database.
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 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 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 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-server-install-dir/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 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:
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 an end user joins the room “joe has joined the room” to “joe has entered the room;” perform the following:
- Edit the IMArchiveDisplay.jsp file with an editor of your choice. For example, you could type the following:
vi IMArchiveDisplay.jsp
- Replace the code line in Code Example 7-3 with Code Example 7-4 in the file IMArchiveDisplay.jsp:
Code Example 7-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 7-4 After replacing the default system message.
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 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 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 Chat Data Based on Time
- 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 Chat Data for the Month of December 2002 to the Subcategory
To Remove Archived Chat Data for the Month of December 2002 from the Portal Server Search Database