## 2.6. Enabling the Instant Messaging component

The fully integrated Instant Messaging System enables the following features in OLAT

- Private Person to Person chat with anybody who is online in OLAT

- Synchronisation of OLAT groups with Roster of Instant Messaing Server. See always the Buddies that are online and available for a chat.

- Roster integrated in OLAT GUI. Instant access to your Buddies wherever you are in the OLAT GUI.

- Groupchat feature for each course and the users Buddygroups.

- Chat and group chat client written in Flash

- OLAT Instant Messaging System based on the Jabber Internet standard (XMPP protocol)( Jabber.org)

### 2.6.1. Basic install with mysql database

Prerequisites

- You can't enable Instant Messaging on the "easy installer". You need to setup a development environement to enable and test the Instant Messaging features. Mainly because of the needed database.

- Instant Messaging Server: Wildfire (formerly knows as JiveMessenger) from jivesoftware.org. An Open Source IM server unter the GPL license written in Java. To download the latest server go to: JiveSoftware download Site and download the version that suits your os best.

- Wildfire needs a Java Virtual Machine > = 1.5. (You can run OLAT as well with java 1.5)

- Mysql database. Wildfire runs also with other databases (like OLAT does) but we only deliver a prepopulated database setup for mysql.

- This installation describes the steps if you run the Wildfire on the same machine together with OLAT and share the same database server, but you can run the IM server as well on another machine.

Installation: Go to OLAT_HOME and edit the build.properties file like:

    #Instant Messaging properties
    instantMessaging.enable=true (enable or disable all instant messaging features)
    instantMessaging.server.name=your.jabber.server
    #(you need a own dns name or just localhost for testing)
    instantMessaging.generateTestUsers=true
    # (the OLAT test users are generated in OLAT with the default passwords also for instant messaging)
    instantMessaging.admin.username=admin
    #(these are the default settings of jivemessenger, Change later!)
    instantMessaging.admin.password=admin

To reflect these changes run an ant taks (run ant tasks inside the OLAT_HOME folder):

    # ant config-all

Now the config file and the database file for the server is generates at OLAT_HOME/conf and you are almost ready to go. Create a database with the name "wildfire" in mysql and populate it with tables and values. Type the following command on the console:

    # mysql -u [olat_db_user] -p
    # create database wildfire;
    # exit;
    # mysql -u [olat_db_user] -p wildfire < OLAT_HOME/conf/instant_messaging_database.sql

Now you should have a database and you only need to copy the Wildfire config file to the place where you dropped and unpacked the downloaded JiveMessenger archive.

    # cp OLAT_HOME/conf/wildfire.xml WILDFIRE_HOME/conf

Your IM server is now ready to be started and tested standalone. To start and stop use either the wildfire file in the WILDFIRE_HOME/ bin directory or if it fails run.

    # cd WILDFIRE_HOME/lib
    # java -jar startup.jar
    You should see an output like:
    Wildfire 2.5.1 Started [Mar 31, 2005 5:37:03 PM]
    Admin console listening at:
      http://localhost:9090
      https://localhost:9091

To test your server go the http://[your-instant-messaging-servername]:9090 and log in as admin/admin and you see the admin console. To test the Instant Messaging features open your favorite jabber client like (Exodus, PSI, Kopete, ...) and log in as one of the OLAT Test users automatically created. (user:administrator/pw:olat - user:author/pw:test - user:test/pw:test)

If you are able to chat with each other you are ready to start OLAT together with the IM server. The IM server should run at the time you start OLAT, otherwise you get an error message that you have enabled Instant Messaging but the server is not running.

### 2.6.2. Features explained

- Technical overview

  The OLAT Instant Messaging system is build with jabber components. The server (Wildfire) implements the XMPP protocol and is compatible with most Jabber clients. OLAT connects to the server using two clients. First with the open source client library SMACK from JiveSoftare and a flash client developt with the XIFF client library that is maintained also by JiveSoftware.

  The SMACK client is used to connect to the server and gets the Roster and manages presence information for the buddies of the connected user. He also receives messages if the flash client is not running. As soon as the flash client gets started all messages are routed to the flash client. The flash client is very limmited in its functionality to serve as an easy client for chat beginners. If people like to use one of the fully featured Jabber clients they can use them too. If you open the flash client you can view the connection settings for this user by clicking "view -> password". The Instant Messaging server decides by the priority of each resource where to send messages. If you use your own jabber client you have to set the resource higher then the SMACK client (priority 0) and lower than the flash client (priority 5) to work best.

- OLAT groups synchronizing with the Wildfire server.

  OLAT provides a tool for managing personal groups with members called OLAT 'groups' When enabling the Instant Messaging features the information from the groups is used to create and maintain a roster in the instant messaging server. The roster stays always visible in the OLAT user interface and provides a overview of the availablity of the users buddies.

  As the Instant Messaging server is completely separated from OLAT the information is synchronized between the components. We have to explain the mechanism first that you understand how the prozess works. As users who log in using the Shibboleth authenitification mechanism don't have a passwort in OLAT. We create an additional account for each user on the IM server. The credentials consits of the OLAT username which is unique in OLAT and a random generated passwort only used for IM. When a user logs into OLAT for the first time OLAT checks if the user has an IM password. If no, a new accounts gets created on the IM server and the password for this IM account is saved in the o_bs_authentication table with the provider name "INST-MSG". On the IM server you should see the created account as well. There are two cases when you need to synchronize OLAT with the Instant Messaging server.

  case 1: You start olat for the first time with Instant Messaging enabled. Here everything should work automatically if you make shure that the IM server is already running befor starting OLAT. In this case OLAT creates the groups and the useraccouts of the members of each group in the IM server. If you log in as a user you should see your groups as a Roster containing the members.

  case 2: In case of a server crash of the IM server or other problems you have to resync the data to make shure both databases are synchron. Shut down Wildfire. Log in to the mysql database:

      # mysql -u [database user] -p
      # use wildfire;
      # delete from jiveGroupUser;
      # delete from jiveGroupProp;
      # delete from jiveGroup;

      # use olat;
      # delete from o_property where name='org.olat.instantMessaging.InstantMessagingModule::issynced';

  Next time you start OLAT it synchronizes again the data between OLAT and the IM server.

- Manually setting the Instant Messaging server properties (setting up the server not with the provided database script)

  The following steps you only have to do if you set up your Instant Messaging database without the provided database script. Go to the admin interface of the server and adjust the following properties.

  - Check the server name: You should use a hostname that gets resolved by the DNS server, otherwise the clients of olat will not be able to connect to the server. Server Settings -> Server Name

  - Registration - Login -> Disable both properties so user cant create accounts themself.

  - Resource Policy -> Choose "Always Kick".

  - Group Chat -> Histroy Settings -> "Show a Specific Number of Messages"

- Using the flash instant messaging client when the Wildfire IM server is installed on an other machine then OLAT itself.

  The flash client can only connect to the same domain where the swf file got loaded from. If you install the IM server on an other host you have to install a simple webserver that delivers the swf file for the chat client over the same server. Otherwiese the flash client refuses connections to this server (Security feature of the flash plugin.).

### 2.6.3. Issues

To decrease memory usage start the server with the following virtual machine parameters. "java -jar -Xss256k startup.jar". This will dramatically decrease memory usage on Linux based systems as only 256KB memory is reserverd for each thread stack (default is 512KB)..