Managing Instant Messenger

This chapter describes how to customize and administer Instant Messenger in the following sections:

Configuring Instant Messenger

There are two ways to invoke and run Instant Messenger:

Using Java Web Start - In this configuration, Instant Messenger is launched as an application from the Java Web Start. The browser is no longer necessary once 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. In addition, the Java plug-in does not allow desktop integration so the Desktop Integration Settings option will not be available from the Settings dialog box.

For more information on how to configure the Java software that enables Instant Messenger, see Setting up and Launching Instant Messenger.

Invoking Instant Messenger

You can invoke Instant Messenger from several locations:

• The index.html file that provides you the options to launch both the Java Web Start and Java Plug-in versions of Instant Messenger. This file also contains links to Instant Messenger documentation.
• A web page you have designed with a link to Instant Messenger.
• A direct URL for either the im.html or im.jnlp files.
• From the command-line.
• Using a desktop shortcut.

Invoking Instant Messenger is described in the following sections:

• To Invoke Instant Messenger Using a Direct URL
• To Invoke Instant Messenger From the Command-Line (Solaris Only)
• To Invoke Instant Messenger Using a Desktop Shortcut

To Invoke Instant Messenger Using a Direct URL

1. Enter the following URL in your web browser to invoke Instant Messenger:

   http://_webserver_:_webserverport_/_path_/_filename_
   

   In this URL,

• webserver Specifies the name of the web container on which you have installed the Instant Messenger resources.
• webserverport (Optional) Specifies the web container port. The default value is 80.
• path (Optional) Specifies the directory where the client files are installed. If the default is selected during the installation, then no subdirectory is required to store the client files.
• filename Specifies the Instant Messenger file to use:
  • index.html - This file is provided with the product. The file contains links to im.jnlp and im.html which launch the Java Web Start and Java Plug-in versions of Instant Messenger respectively.
  • im.jnlp - The .jnlp file to launch only the Java Web Start version of Instant Messenger.
  • im.html - The web page to launch only the Java Plug-in version of Instant Messenger.

To Invoke Instant Messenger From the Command-Line (Solaris Only)

1. Type the following at the command-line:
   javaws_cmd URL
   See [To Invoke Instant Messenger Using a Direct URL] for information about constructing the URL.

To Invoke Instant Messenger Using a Desktop Shortcut

1. Create and use a desktop shortcut to invoke Instant Messenger

• Create a shortcut using Java Web Start.
• Create a shortcut manually and set the target value as follows:
  javaws_cmd jnlp-URL
  Where jnlp-URL is the URL to the im.jnlp file.

Top

Changing the Codebase

The codebase is the URL from which Instant Messenger accesses resources, including the start page for initial downloads of the Instant Messaging client. This URL is defined during postinstallation configuration when the resource files are deployed by the configure utility. If you change any portion of the URL used to access Instant Messenger resources including the web container port number you need to update the codebase.

If you want to change the codebase after you have deployed the resource files you will need to:

• Modify the template files to point to the new URL. See To Change the Codebase in the Resource Templates.
• Run the configure utility, selecting the “Messenger Resources” component only when prompted for which components you want to configure. See Configuring Instant Messaging After Installing or Upgrading for instructions.
• Redeploy the resource files. See Redeploying Resource Files for instructions.

To Change the Codebase in the Resource Templates

1. Edit each of the template files in the im-svr-base/html directory with the new URL.
   Template files are named *.template. See Instant Messenger Resource Files for a complete list of template files.

Changing the Web Container Port

If you change any portion of the URL used to access Instant Messenger resources including the web container port number you need to update the codebase. See Changing the Codebase for instructions.

Customizing Instant Messenger

Instant Messenger is customizable. HTML and JNLP files can be customized to suit an organization's specific needs. If you want to customize the resource files for your deployment, you should run the configure utility (if you haven’t already done so after installing), customize the files, then redeploy the resource files. You need to run the configure utility first because configure creates some of the files that you can customize. (See Redeploying Resource Files for redeployment instructions.)

You can customize Instant Messenger to meet your requirements in the following ways:

• Instant Messenger Resource Files
• Customizing the index.html and im.html Files
• Launching Instant Messenger Using Sun Java System Access Manager SSO
• Customizing the Application (Java Web Start)
• Rebranding Instant Messenger
• Customizing User Name and Group Name Display

This section describes the Instant Messaging server files you can modify to customize Instant Messenger. The files that you can customize are all located in the resource directory im-svr-base/html directory. See Table 3-1 for information on default directory locations.

Instant Messenger Resource Files

The Instant Messenger resource files are located within a directory referred to as the resource directory or im-svr-base/html.

Table 15-1 contains the list of Instant Messenger files in the resource directory (im-svr-base/html). It also contains the description and customization information for these files. Within the resource directory, the /locale subdirectory is represented generically in a directory path as lang, but specifically as abbreviations of languages, such as, en_US, jp, and fr_FR.

Table 15-1 Instant Messenger Resource Files in im-svr-base/html

Customizing the index.html and im.html Files

If you are using Instant Messenger in a deployment without Sun Java System Access Manager, you can 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:

• Images
• Banner
• Text on screen including title and field labels
• Background schemes

You can launch the Instant Messenger applet and the Java Web Start application from index.html. 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 file is generated when you run the configure utility and contains an applet argument that points to the multiplexor.

Note The argument “<PARAM NAME="server" VALUE="servername">” represents the Instant Messaging multiplexor and its port in the im.html file. If you change the iim_mux.listenport parameter’s default value, you need to change the servername value to host.domain:port.

Launching Instant Messenger Using Sun Java System Access Manager SSO

To launch the Instant Messenger client using single sign-on (SSO) with Sun Java System Access Manager use IMLaunch.jsp. This file is in the resource directory.

Sun Java System Access Manager and Instant Messenger must be configured to use the same web container to enable SSO.

To launch Instant Messenger enter the following in a web browser:

codebase/IMLaunch.jsp?server=multiplexor-hostname:muliplexor-port

or

codebase/IMLaunch.jsp?server=www.example.com:5222

Where:

• codebase is the codebase from which the Instant Messenger resources are downloaded. For example, http://www.example.com.

• multiplexor-hostname is the host name of the mulitplexor. For example, http://www.company22.com.

• muliplexor-port is the port number on which the multiplexor listens for incoming client requests. For example, 5222.

• IMLaunch.jsp is used for launching Instant Messenger through either Java Web Start or Java Plug-in.

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 customize the user interface. The following are modifications that can be made to these files:

• 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 on imbrand.jar contents, see Contents of imbrand.jar.
  Use the following command to extract imbrand.jar:

  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 .wav 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. The same is possible with the audio files (.wav files).

• im.jnlp - this file invokes the Java Web Start version of the Instant Messenger application. You can modify the codebase, title, vendor, and descriptions in the file.
  Example 15-1 shows a sample im.jnlp file with the HTML code that can be customized in bold typeface.

Example 15-1 Sample im.jnlp File

<?xml version="1.0" encoding="utf-8"?>
<!-- Instant Messenger -->
<jnlp
  spec="1.0+"
  codebase="http://im.i-zed.com:80/im"
  href="en/im.jnlp">
  <information>
    <title>Instant Messaging</title>
    <vendor>I-Zed.com</vendor>
    <homepage href="http://www.I-zed.com/"/>
    <description>I-Zed’s Sun Java System Instant Messenger</description>
    <description kind="short">Instant Messenger</description>
    <icon href="CompanyLogo.gif"/>
    <offline-allowed/>
  </information>
  <security>
    <all-permissions/>
  </security>
  <resources>
    <j2se version="1.3+">
      <resources>
        <jar href="en/imres.jar"/>
        <jar href="en/imbrand.jar"/>
      </resources>
    </j2se>
    <jar href="messenger.jar"/>
    <jar href="imdesktop.jar"/>
    <jar href="imnet.jar"/>
    <jar href="icalendar.jar"/>
    <nativelib href="imjni.jar"/>
  </resources>
  <application-desc main-class="com.iplanet.im.client.iIM">
    <argument>server=im.i-zed.com:45222</argument>
    <argument>help_codebase=http://im.i-zed.com:80/im/en</argument>
  </application-desc>
</jnlp>

Note In the im.jnlp file, the argument <argument>servername</argument> represents the Instant Messaging multiplexor host and port. If you change the default value of the iim_mux.listenport parameter , you need to change the servername value to host.domain:port.

Contents of imbrand.jar

The tables in this section list the files in the imbrand.jar file and provide a description of each file wherever possible. The imbrand.jar file also contains the image and audio files you can use to re-brand Instant Messenger. This section contains the following tables:

• Table 15-2 - configuration files used to configure Instant Messenger.
• Table 15-3 - emoticons available for use during chat sessions.
• Table 15-4 - icons used by the application on Windows.
• Table 15-5 - icons used by the application on all platforms.
• Table 15-6 - icons used in the toolbar.
• Table 15-7 - icons used in the contact list.
• Table 15-8 - icons used to describe presence information in the contact list.
• Table 15-9 - icons used to describe presence information in the status bar.
• Table 15-10 - available backgrounds.
• Table 15-11 - sounds used to indicate alerts and status or configuration changes.

Table 15-2 Configuration Files

Table 15-3 Emoticons

Table 15-4 Application Icons - Windows

Table 15-5 Application Icons - All Platforms

Table 15-6 Toolbar Icons

Table 15-7 Contact List Icons

Table 15-8 Presence Icons - Contact List

Table 15-9 Presence Icons - Status Bar

Table 15-10 Backgrounds and Background Swatches for the Palette

Table 15-11 Sounds

Rebranding Instant Messenger

The imbrand.jar file contains all images and the properties that control the look and feel of Instant Messenger. You can customize the appearance of Instant Messenger by modifying the images and the properties in imbrand.jar.

To Rebrand Instant Messenger

1. Copy imbrand.jar file to a working directory.
   For example:
   cp im-svr-base/html/lang/imbrand.jar working-directory
2. Change to the working directory.
   cd working-directory
3. 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 imbrand.jar file.
   Alternatively, you can extract a single file included in imbrand.jar and put it under the directory structure you specify. For example, to extract only brand.properties, use the following command:
   jar xf imbrand.jar com/sun/im/desktop/brand/brand.properties
4. Update imbrand.jar with the modified .gif, .wav, and .properties files.
   You can update all the files in imbrand.jar as follows:
   jar cf imbrand.jar .
   To update imbrand.jar with a single modified file, use the following command:
   jar uf imbrand.jar com/sun/im/desktop/brand/filename
   Where filename is the name of the file included in imbrand.jar, for example, brand.properties.
5. Copy imbrand.jar to the resource directory.
   For example:
   cp imbrand.jar im-svr-base/html/lang/ .

   Note If you support multiple locales in your deployment, follow the procedure for rebranding Instant Messenger for every supported locale.

Customizing User Name and Group Name Display

You can customize how Instant Messenger displays contact and group names by changing the attribute used to display contact names. By default, the Instant Messenger uses the attribute cn to represent a user's display name. In your deployment, you may prefer to use uid or some other attribute instead of cn.

Contact names appear as First Name, Last Name. For example, Frank Smith, Mary Jones, and so on. When two end users have the same first name and last name, it is impossible to know which end user has to be added to the contact list. You can customize Instant Messenger to display more information in the search results for the user search, and to display additional information in the Contact tooltip to help distinguish between contacts. For example, you can display the phone number of the Contact when the mouse is placed over the Contact.

To Change the Attribute Used to Display a User's Name

1. Open iim.conf.
   See iim.conf File Syntax for instructions on locating and modifying iim.conf.
2. Specify the attribute you want to use to display usernames as the value for iim_ldap.userdisplay.
   For example, to use the nickname attribute, set the iim_ldap.userdisplay attribute as follows:
   iim_ldap.userdisplay=nickname
3. Save and close the file.

To Change the Attribute Used to Display a Group's Name

1. Open iim.conf.
   See iim.conf File Syntax for instructions on locating and modifying iim.conf.
2. Specify the attribute you want to use to display usernames as the value for iim_ldap.groupdisplay.
   For example, to use the uid attribute, set the iim_ldap.groupdisplay attribute as follows:
   iim_ldap.groupdisplay=uid
3. Save and close the file.

To Customize User Name Display in Search Results

1. Extract the files from imbrand.jar.
   See Table 15-1 for default locations for imbrand.jar
2. Change to the following directory:
   com/sun/im/client/
3. Open brand.properties.
4. Add the dialogs.searchresults.format attribute to the file.
5. Add the attributes you want to include in search results in the following format:

    (${attr:attribute-name} 

   Where attribute-name is the name of the LDAP attribute.
   For example, to include the title attribute, add the following line:

    dialogs.searchresults.format=(${attr:title}) 

6. Save your changes and close the file.
7. Repackage imbrand.jar.
8. Add the user attributes to iim.conf.
   Specify the attributes as values for the iim_ldap.userattributes parameter. Separate multiple attributes with a comma, for example:
   iim_ldap.userattributes=title,department,telephonenumber
   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

To Customize Tooltip Contents

1. Extract the files from imbrand.jar.
   See Table 15-1 for default locations for imbrand.jar
2. Change to the following directory:
   com/sun/im/client/
3. Open brand.properties.
4. Add the contact.tooltip.format.html attribute to the file.
5. Specify the attribute you want to display in the tooltip as the value for contact.tooltip.format.html.
   For example, if you want to display the telephone number and email address of the contact, you would enter:

    contact.tooltip.format.html=mailto:${attr:mail} tel:${attr:telephonenumber} 

   For more information on customizing the contents of imbrand.jar file, see Customizing the Application (Java Web Start).

6. Save your changes and close the file.
7. Repackage imbrand.jar.

Top

Modifying How Client Users Search for Contacts

By default the commonname or cn LDAP attribute is used as a search attribute for users. You can configure Instant Messaging to allow users to search on additional attributes. In addition, If your directory is indexed to allow the use of wildcards, you can configure the Instant Messaging server to allow wildcards in searches for contact names.

To Allow Users to Search on Custom Attributes

1. Open iim.conf.
   See iim.conf File Syntax for instructions on locating and modifying iim.conf.
2. Modify the iim_ldap.usergroupbynamesearchfilter attribute.
   This parameter specifies the LDAP search string used when searching for users or groups. Provide the attribute value in standard LDAP filter syntax. You can modify it to allow more complex searches. See your Directory Server documentation for more information on modifying search strings.
3. Save and close the file.

To Allow Wildcards in Searches

1. Open iim.conf.
   See iim.conf File Syntax for instructions on locating and modifying iim.conf.
2. Set the iim_ldap.allowwildcardinuid parameter to True.
   This parameter determines if the use of wildcards should be enabled for User IDs while doing a search. Most directory installations have User IDs indexed for exact searches only, so the default value is False.
3. Ensure that User IDs are indexed for substring search in your directory.
   Setting the iim_ldap.allowwildcardinuid parameter to True can impact performance unless User IDs are indexed for substring search in your directory. See your directory server documentation for instructions on indexing.

Administering Conference Rooms and News Channels

The administrator can create conference rooms and news channels for end users. However, with the proper privileges, end users can do this also. For more information about adding policies to give end users access to create conference rooms and news channels, see 17 Managing Instant Messaging and Presence Policies. End 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.

Listed below are tasks that you can perform in Instant Messenger to administer the conference rooms and the news channels. For more information on performing these tasks, see the Online Help.

• Administering conference rooms
• Administering and managing news channels
• Assigning conference room access levels to end users
• Assigning news channel access levels to end users
• Assigning end users to conference rooms
• Assigning end users to news channels (subscribing)
• Creating new conference rooms
• Creating new news channels
• Configuring end user settings
• Deleting conference rooms
• Deleting messages from news channels
• Deleting news channels
• Posting messages in news channels
• Removing end users from conference rooms
• Removing end users from news channels

Top

Modifying Instant Messenger Proxy Settings

Instant Messaging 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.

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 Proxy Settings Manually for a Single Instant Messenger Client Using Java Web Start

Completing this procedure saves proxy preferences in the user's messenger.properties file. If you also configure the im.jnlp file to use a proxy, and the proxy differs from that in the user's preferences, the user's preferences are used.

1. Invoke Java Web Start.
2. From the File menu, choose Preferences.
3. Select Manual option in the Preferences dialog.
4. 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.
5. Click OK to save the proxy settings.

To Configure Proxy Settings for all Instant Messaging Client Connections in im.jnlp

If the proxy you set in im.jnlp differs from that in the user's preferences file (/usr_home/.sunmsgr/messenger.properties), the user's preferences are used.

1. Open the im.jnlp resource file in a text editor.
2. Specify the proxy server by adding the following argument:

   <argument>proxy=_proxy-host:proxy-port_</argument>
   

   Where proxy-host is the fully-qualified domain name of the proxy server and proxy-port is the port number on which the proxy server listens for incoming requests. For example, myproxy.siroe.com:8080.

3. Specify the proxy type by adding the following argument:

   <argument>proxy_type=_type_
   

   Where type can be one of http, https, or socks.

Top

Controlling the Exposed Messenger Feature Set

You can control the exposed feature set of Instant Messenger by configuring the Instant Messaging applet parameters in the applet descriptor files.

Table 15-12 shows the Instant Messenger applet parameters in the applet descriptor files. It also contains the description and the default values of these parameters.

Table 15-12 Instant Messenger Applet Parameters

Instant Messenger Data Stored in the End User's System

Instant Messenger caches a limited amount of information on the end user’s system for auto-login. This information is located at:

home-directory/.sunmsgr

home-directory is the end user's home directory. The home directory of the end user can be obtained from the user.home parameter in the Java system property.

Table 15-13 shows the directories and files containing the cached data. It also contains the description of the files and the directories.

Table 15-13 Cached Data Directory and Files

Table 15-14 shows the auto-logon properties for Instant Messaging. It also contains the description and the default values of these properties.

Table 15-14 Auto-logon Properties

Top

Redeploying Resource Files

If you are using Sun Java System Application Server or Sun Java System Web Server, and you make changes to the resource files after you run the configure utility as a result of site changes or customization, you need to redeploy the files to the web container. You may also need to redeploy the resource files after upgrading Instant Messaging.

To Redeploy Resource Files to Sun Java System Application Server or Sun Java System Web Server

1. Run the iwadmin command.
   im-svr-base/html/iwadmin
   Where im-svr-base is the directory in which you installed Instant Messaging.
   Running iwadmin updates the Instant Messenger .jar files. However, iwadmin does not update or reinitialize the Instant Messenger download page. See the documentation for your web container for additional information. Also see the iwadmin man page for additional configuration options.
2. (Optional) After upgrading, if you want to reinitialize the Instant Messenger download page, run the configure utility again.
   Reinitializing the download page overwrites any customizations you have made. If you choose not to reinitialize the download page, be aware that the product version on the download page and the product version in the Instant Messenger .jar files may differ.
   See Configuring Instant Messaging After Installation for more information.