This chapter explains how to configure and manage email, Portal, and custom archiving for Instant Messaging in the following sections:
You can archive instant messages in the following ways:
Using the Portal Server Search-based Archive. This method captures instant messages and archives these messages in a Portal Server Search database. End users can query and retrieve archived messages using the Search page on the Portal Server desktop.
Using the Email Archive. When using this method, chat and conference participants receive emails containing the contents of the Instant Messaging sessions in which they participated. End users can use any email client to search and manage instant messages.
Using a Custom Archive. You can choose to use either the Instant Messaging archive providers, or create your own custom archive provider. Instant Messaging provides the APIs and SPIs that can be used to write custom archive providers. For more information on Instant Messaging APIs, see Appendix D, Instant Messaging APIs. Regardless of which type of archive provider you choose to use, you need to enable the archive provider in iim.conf.
You can configure Instant Messaging to use one or more archive methods at the same time.
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.
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:
Open iim.conf.
See iim.conf File Syntax for information.
Add the following line to iim.conf if it does not already exist.
iim_server.msg_archive = true |
Save and close iim.conf.
Refresh the server.
imadmin refresh server |
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:
Open iim.conf.
See iim.conf File Syntax for information.
Set the iim_server.msg_archive parameter to false.
iim_server.msg_archive = false |
Save and close iim.conf.
Refresh the server.
imadmin refresh server |
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.
You enable or disable the email archive provider by modifying a parameter value in iim.conf.
Ensure that you have enabled archiving for Instant Messaging as described in To Enable Instant Messaging Archiving.
Open iim.conf.
See iim.conf File Syntax for more information.
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 |
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |
Open iim.conf.
See iim.conf File Syntax for more information.
Delete the com.iplanet.im.server.EmailIMArchive value from the iim_server.msg_archive.provider parameter.
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |
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.
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. |
Open iim.conf.
See iim.conf File Syntax for more information.
Add the parameters in Table 18–1 and appropriate values to iim.conf.
Refresh the server.
imadmin refresh |
The RFC 822 header content for email messages containing various types of archived Instant Messaging content is described in the following sections:
Chat session initiator.
Receiver and any administrators configured in iim.conf. See Table 18–1 for more information.
Chat session initiator.
First useful message over 50 characters in length.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider based on the message thread.
Chat session initiator.
Other participants and any administrators configured in iim.conf. See Table 18–1 for more information.
Chat session initiator.
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.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider based on the conference ID.
Room owner in archive data.
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.
Not used.
[Conference name] subject.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider based on the conference ID.
Poll sender.
Poll sender and any administrators configured in iim.conf. See Table 18–1 for more information.
Not used.
Poll question.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider.
Poll sender.
Poll recipients and any administrators configured in iim.conf. See Table 18–1 for more information.
Poll sender.
Poll question.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider.
Alert sender.
Alert recipients and any administrators configured in iim.conf. See Table 18–1 for more information.
Not used.
Alert subject.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider.
News channel post sender.
Mailing list associated with the news channel and any administrators configured in iim.conf. See Table 18–1 for more information.
Not used.
News channel post subject.
Creation date of the email message by the archive provider.
Not used.
Generated by the email archive provider based on the news channel ID.
The following topics describe using the Instant Messaging Portal Archive:
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.
You enable the Instant Messaging Archive Provider or your custom archive provider by modifying parameters in iim.conf.
Ensure that you have enabled archiving for Instant Messaging as described in To Enable Instant Messaging Archiving.
Open iim.conf.
See iim.conf File Syntax for instructions on locating and modifying iim.conf.
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 |
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" |
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |
Log in to psconsole
as amadmin.
For instructions, refer to the Portal Server documentation.
Select Manage Channels and Containers.
Select the portal and organization that will host the search function.
Select IMChannel from the DP XML Tree View.
Enter the search server URL as the value for “searchServer”.
For example:
http://portal.siroe.com:8080/search1/search |
Save properties.
Open iim.conf.
See iim.conf File Syntax for more information.
Delete the com.iplanet.im.server.IMPSIMArchive value from the iim_server.msg_archive.provider parameter.
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |
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.
Open iim.conf.
See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying iim.conf.
Add or edit the archive provider configuration parameters as desired.
See Table A–8 for a list of parameters you can modify.
Save and close iim.conf.
Refresh the Instant Messaging server.
Use this procedure to configure Instant Messaging to store archived messages in a database other than the default.
Open iim.conf.
See Appendix A, Instant Messaging Configuration Parameters in iim.conf for instructions on locating and modifying 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 and close iim.conf.
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.
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.
Create a back up of the IMArchiveDisplay.jsp file.
Open the IMArchiveDisplay.jsp file.
Search through the IMArchiveDisplay.jsp file and locate the following two lines of code:
<search:setQuery query = "<%= scope %>"/> <search:setRDMType rdmType = "rd-request"/> |
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.
Replace the virtual search server with the physical server hostname.
Save and close IMArchiveDisplay.jsp.
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.
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.
Change to the https-servername directory.
cd /var/opt/SUNWps/https-servername |
Where servername is the name of the Portal Server
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.
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" |
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" |
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.
Edit IMArchiveDisplay.jsp.
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>"); .... |
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>"); .... |
This sample deployment scenario explains how 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 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
Change to theim-cfg-base directory.
See Instant Messaging Server Directory Structure for information on locating im-cfg-base.
Open iim.conf.
See iim.conf File Syntax for instructions on locating and modifying iim.conf.
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.
Type the following:
rdmgr -Q "classification=Archive:Chat:2005:12" > archive.soif |
Copy the archive.soif file to your backup system.
In addition to the Portal and email archives, you can choose to use a custom archive provider.
Ensure that you have enabled archiving for Instant Messaging as described in To Enable Instant Messaging Archiving.
Open iim.conf.
See iim.conf File Syntax for instructions on locating and modifying iim.conf.
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 |
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |
Open iim.conf.
See iim.conf File Syntax for more information.
Delete only the value for the custom archive provider from the iim_server.msg_archive.provider parameter.
Save and close iim.conf.
Refresh the Instant Messaging server configuration.
imadmin refresh |