| Sun ONE Instant Messaging Administrator's Guide |
Chapter 3
Managing Instant MessengerThis chapter describes how to customize and administer Sun ONE Instant Messenger.
This chapter contains the following:
Configuring Sun ONE Instant MessengerThere are two ways to configure and invoke Instant Messenger:
- Using Java Web Start - In this configuration, Instant Messenger is launched as an application from the Java Web Start. The browser dependency is removed once the Instant Messenger is launched.
- Using the Java Plug-in - In this configuration, Instant Messenger is run as a Java applet. To keep the Instant Messenger session active, the browser window from which the applet was launched must remain open and cannot be used to locate any other URL.
For more information on how to configure the Java software that enables Instant Messenger, see the Sun One Instant Messaging Installation Guide.
Invoking Instant MessengerYou can invoke Instant Messenger using:
- The index.html file provides you the options to launch both the Java Web Start and Java Plug-in versions of the Instant Messenger. This file also contains links to Instant Messenger documentation.
- The web page that you have designed with a a link to the Instant Messenger.
- Providing a direct URL for either the im.html or im.jnlp files.
To Invoke the Instant Messenger
Use the following URL to invoke the Instant Messenger.
http://webserver:webserverport/subdirectory/filename
In this URL,
You can also, do the following:
Solving Web Server IssuesThis section contains web server issues that apply to standalone deployments and also to portal deployments, where the Instant Messenger is not installed on the Portal Server host and uses a different Web Server to serve Instant Messenger.
Changing the Codebase
By default, Instant Messaging fetches the Instant Messenger resources installed in the web server’s document root. If you have installed the Instant Messenger files in a directory other than the web server document root, you will need to know the following details:
- URL to launch Instant Messenger - The URL that is used by the users to access the index.html (and im.html and im.jnlp files). This URL needs to reference the Instant Messenger installation directory.
For example, if the Sun ONE Instant Messaging server host is iim.i-zed and the Instant Messenger files are installed in the /opt/SUNWiim/html directory, you need to create a symbolic link such as iim, which points to the web server’s document root /opt/SUNWiim/html. The users can access the Instant Messenger main page index.html using the following URL:
- Launch the Instant Messenger using Java Web Start- If the Instant Messaging Codebase specified during the installation is changed then you need to change the codebase parameter in the im.jnlp file to reference the web server and the Instant Messenger path. The following is the change to the codebase parameter:
codebase= http://servername:port/path/
You need to include the port number of the web server if it is not configured to the default value 80.
For example, if the Sun ONE Instant Messaging server host is iim.i-zed and the Instant Messenger files are installed in the /opt/SUNWiim/html directory, you can create a symbolic link such as iim which points to /opt/SUNWiim/html in the web server’s document root. Then change the codebase parameter in the im.jnlp file to the following:
codebase="http://iim.i-zed.com/iim/"
Changing Web Server Port
If your web server is installed on a port other than the default (80), you need to know the following details:
Customizing Instant MessengerWhile designed to work right out of the box, Instant Messenger is also customizable. Instant Messenger consists of HTML and JNLP files that can be customized to suit an organization's specific needs.
You can customize the Instant Messenger to meet your requirements in the following ways:
This section describes the Instant Messaging server files you can modify to customize the Instant Messenger. The files that you can customize are all located in the html directory. For example, on Solaris the HTML files are located in the imdocroot directory.
Instant Messenger ResourcesInstant Messenger Files
The Instant Messenger files are located in the imdocroot directory.
Table 3-1 contains the list of Instant Messenger files in the imdocroot directory. It also contains the description and the customization information of these files. The imdocroot directory contains lang which is the locale subdirectory. For example, en_US, jp, fr_FR.
Customizing the index.html and im.html Files (Only Standalone Deployments)
The Instant Messenger allows you to modify the “static” portion of the index.html and im.html files to produce a fully customized user interface. These HTML files contain both text and markups describing how the text is formatted and handled. Markup is implemented through a set of tags, which specify formats for headers, indents, font size, and font style.
Some of the page elements that can be modified are:
The index.html file launches both the Instant Messenger applet and the Java Web Start application. If you are running the Instant Messenger applet, modify the im.html file. The im.html file is called by index.html, and invokes the Instant Messenger applet. The im.html is generated during the installation and contains an applet argument that points to the multiplexor.
Customizing the Application (Java Web Start)
If you are running Instant Messenger using Java Web Start, you can modify the im.jnlp, imres.jnlp, and imres.jar files to customized the user interface. The following are modifications that can be made to these HTML files:
Table 3-2 shows the sample im.jnlp file, with the HTML code that can be customized in bold typeface.
Table 3-2 The sample im.jnlp file.
.
Note
In the im.jnlp file, the argument <argument>servername</argument> represents the Sun ONE Instant Messaging multiplexor host and port. If you change the default value of iim_mux.listenport parameter, you need to change the servername value to host.domain:port.
- imbrand.jar - This file contains the image and audio files, and the properties that can be customized. You need Java Developers Kit 1.3(JDK) to extract the contents from the imres.jar file using the jar command. For more information of the imbrand.jar file contents, see Contents Listing of imbrand.jar file.
The following is the syntax for the jar command:
jar xvf imbrand.jar
This command creates a directory tree where the resource files are copied. This directory structure has to be maintained when you modify the individual files in the jar file.
You can substitute your version of .gif files or .au files, without changing the file names and then place the changed files back to the directory using the following jar command:
jar -uf imbrand.jar com/Sun/im/client/images/*.gif
This command updates the imbrand.jar file with the modified .gif files. You can also do the same with the audio files (.au files).
Contents Listing of imbrand.jar
Table 3-3 lists the files in the imbrand.jar file and their description. The imbrand.jar file contains the image and audio files that can be used to re-brand the Instant Messenger.
Table 3-3 Contents Listing of imbrand.jar file.
File Name
Description
Angry_16.gif
An emoticon used to show angry emotion graphically.
Devil_16.gif
An emoticon used to show devilish emotion graphically.
Laugh_16.gif
An emoticon used to show laugh emotion graphically.
Angel_16.gif
An emoticon used to show angelic emotion graphically
Smiley_16.gif
An emoticon used to show smile emotion graphically.
Love_16.gif
An emoticon used to show love emotion graphically
Grin_16.gif
An emoticon used to show grin emotion graphically.
Wink_16.gif
An emoticon used to show wink emotion graphically.
Sad_16.gif
An emoticon used to show sad emotion graphically.
Suprise_16.gif
An emoticon used to show suprise emotion graphically.
Away_13.gif
Icon for away status that appears in the Change Status menu.
Online_13.gif
Icon for online status that appears in the Change Status menu.
Offline_13.gif
Icon displayed when the user is away or not connected that appears in the Change Status menu.
Idle_13.gif
Icon for idle status that appears in the Change Status menu.
Forwarded_13.gif
Icon displayed against users when they are offline and have set alerts to be forwarded to email. This icon appears in the Change Status menu.
Away_13Padded.gif
Icon for away status that appears in the contact list.
Idle_13Padded.gif
Icon for idle status that appears in the contact list.
Online_13Padded.gif
Icon for online status that appears in the contact list.
Offline_13Padded.gif
Icon for offline status that appears in the contact list.
Forwarded_13Padded.gif
Icon displayed against users when they are offline and have set alerts to be forwarded to email. This icon appears in the contact list.
Away_24.gif
Icon for away status that appears in the status bar.
Online_24.gif
Icon for online status that appears in the status bar.
Offline_24.gif
Icon for offline status that appears in the status bar.
tray_icon.ico
Instant Messenger icon that appears on the task bar.
app_icon.gif
The Instant Messenger application icon.
logon_splash.gif
The Sun ONE logo displayed in the Login and About boxes
alert.au
Sound when user receives an alert.
away.au
Sound when the user changes status to away.
soundon.au
Sound when user exits Instant Messenger.
soundoff.au
Sound when user logs on to Instant Messenger.
send.au
Sound when user sends an instant message.
receive.au
Sound when user receives an instant message.
Rebranding Instant Messenger
The imbrand.jar file contains all images and the properties that control the look and feel of the Instant Messenger. You can customize the appearance of the Instant Messenger by modifying the images and the properties in the imbrand.jar file.
To re-brand the Instant Messenger:
- Copy imbrand.jar file to a working directory and change to this directory. For example:
cp imdocroot/lang/imbrand.jar working_directory
- Extract the imbrand.jar file.
jar xf imbrand.jar
This command creates a directory tree where the resource files are copied. This directory structure has to be maintained when you modify the individual files in the jar file.
- Update the imbrand.jar file with the modified .gif files and .au files.
jar cf imbrand.jar .
- Copy the imbrand.jar file to the imdocroot directory. For example:
cp imbrand.jar imdocroot/lang/.
Customizing User Name Display
The User Name display can be customized in the tooltip and the search results.
Customizing User Name Display in Search Results
When two users have the same first name and last name, it is impossible to know which user has to be added to the contact list. You can customize the Instant Messenger to display more information in the search results for the user search. For displaying more information in the user search results, in the imbrand.jar file you need to add dialogs.searchresults.format attribute to the brand.properties file at:
com/sun/im/client/
For more information on how to modify imbrand.jar, see Customizing the Application (Java Web Start).
More information can be displayed in the user search results by including additional LDAP attribute values in the dialogs.searchresults.format attribute.
The LDAP attributes are specified in the following format:
${attr:attribute-name}
The following example shows the LDAP attribute in dialogs.searchresults.format attribute:
dialogs.searchresults.format=(${attr:title})
To use random attributes from the LDAP user entry, the list of these custom attributes needs to be specified in the server configuration file iim.conf. These custom attributes need to be specified as values for the attribute iim_ldap.userattributes.
The following example shows the iim_ldap.userattributes with the list custom attributes as value:
iim_ldap.userattributes=title,department,telephonenumber
Customizing User Name Display in Tooltip
You can customize the Instant Messenger to display additional information in the Contact tooltip.
For example, to display the phone number of the Contact when the mouse is placed over the Contact:
- Change to the following directory:
com/sun/im/client/
- Open the brand.properties file.
- Add the contact.tooltip.format.html attribute to the file.
- Save the changes to the file
- Change to the following directory.
cd imdocroot
- Add the contact.tooltip.format.html attribute and the telephonenumber attribute as its value in the HTML code of the imbrand.jar file:
contact.tooltip.format.html=mailto: ${attr:mail} tel: ${attr:telephonenumber}
For information on customizing the imbrand.jar file, see Customizing the Application (Java Web Start).
Administering Instant Messenger Conference Rooms and News ChannelsListed below are tasks that you can perform in the Instant Messenger to administer the conference rooms and the news channels. For more information on performing these tasks, see the Instant Messenger Online Help.
- Administering conference rooms
- Administering and managing news channels
- Assigning conference room access levels to users
- Assigning news channel access levels to users
- Assigning users to conference rooms
- Assigning users to news channels (subscribing)
- Creating new conference rooms
- Creating new news channels
- Configuring user settings
- Deleting conference rooms
- Deleting messages from news channels
- Deleting news channels
- Posting messages in news channels
- Removing users from conference rooms
- Removing users from news channels
Granting Users Privilege to Create Conference Rooms and News Channels
The administrator can create conference rooms and news channels for users. However, individual users can also create conference rooms and news channels, if they have the privileges to add conference rooms and news channels. The users who create a conference room or a news channel by default have Manage access, enabling them to administer the conference room or the news channel.
For more information on managing user privileges, see Managing User Privileges.
Modifying Instant Messenger Proxy SettingsThe instant messages can contain embedded URLs. For example, http://stocks.yahoo.com?id=sunw. If you are using proxy servers, you need to resolve such embedded URLs by modifying the Instant Messenger proxy settings in the Java Web Start configuration.
This is likely to happen if your organization has a firewall, and you need to go through the proxy server before connecting your client hosts to internet, and if Java Web Start has not been configured with the right proxy settings.
To Modify Instant Messenger Proxy Settings
Java Web Start can automatically configure the proxy settings by querying the system or the default browser. However, it is not possible for the Java Web Start to automatically configure these settings if the proxy settings are configured using a JavaScript file.
To set the proxy settings manually:
- Invoke Java Web Start.
- From the File menu, choose Preferences.
- Select Manual option in the Preferences dialog.
- Enter the following details:
HTTP Proxy. Enter the Name or the IP address of the proxy server.
HTTP Port. Enter the port number of the proxy server.
No Proxy_Hosts. Enter the name of any domain that you can connect directly, bypassing the proxy server. Use commas to separate multiple host names.
- Click OK to save the proxy settings.
Controlling The Exposed Messenger Feature SetThe exposed feature set of the Instant Messenger can be controlled by the administrator by configuring the Instant Messaging applet parameters in the applet descriptor files.
Table 3-4 shows the Instant Messenger applet parameters in the applet descriptor files. It also contains the description and the default values of these parameters.
Table 3-4 Instant Messenger Applet Parameters
Parameter
Default Value
Description
server
127.0.0.1
The Instant Messaging server host and port.
debug
FALSE
If this parameter is set to true, the applet records all the task performed on java console.
uid
This parameter is used for SSO.
token
This parameter contains SSO token and is used for auto-logon.
secure
FALSE
Indicates to the messenger that it is run in SRA mode. It displays secure indicator.
usessl
FALSE
Tells messenger to use SSL when connecting to server.
allow_alert_only
FALSE
Tells messenger to let user display neither the contact list nor the news channel.
This parameter is used in CHAT and POPUP flavors.
allow_file_transfer
TRUE
Allows file attachment and transfer.
flavor
ALL
Flavor to be used. The Supported values are ALL(default), IM, NEWS, CHAT and POPUP.
ALL: All services are enabled.
IM: presence, conferencing and alert (notification) services are enabled.
NEWS: Only news and alert services are enabled. Presence/contact list are not.
CHAT: only the private conference service is accessible.
POPUP: the messenger is only capable of receiving alerts.
enable_moderator
TRUE
If set true, enables the moderated conference feature.
messenger_bean
This parameter contains a list of messenger beans to be used. You can enter multiple factory class names separated by comma.
gateway_url
This parameter contains the URL of the gateway component of portal SRA.
Instant Messenger Data Stored in the End User’s SystemInstant Messenger caches limited amount of information on the end user’s system for auto-login. This information can be located at:
${HOME}/.sunmsgr
${HOME} is the user's home directory. The home directory of the user can be obtained from the user.home parameter in the Java system property.
Table 3-5 shows the directories and files containing the cached data. It also contains the description of the files and the directories.
Table 3-5 The directory and files containing the Cached Data
File/Directory Name
Type
Description
.sunmsgr/messenger.properties
file
The file containing the auto-logon properties
.sunmsgr/<user_domain>/
directory
Directory containing data specific to a particular {loginname- domainname} combination.
.sunmsgr/<user_domain>/messenger.properties
file
This file contains auto-logon options specific to particular <user_domain>. This file is not used.
.sunmsgr/<user_domain>/messages/
directory
This directory contains cached messages. This directory is not used.
Table 3-6 shows the auto-logon properties for Instant Messaging. It also contains the description and the default values of these properties.
Table 3-6 The Auto-logon Properties
Parameter
Default Value
Description
net.server
127.0.0.1
Instant Messaging server host name and port.
net.server.n
The secondary servers' host names and port numbers.
net.user
The default user id
net.pass
The encoded user password that enables auto-logon.
