MSG Installation Guide (for developers)

MSG Installation Guide

To install MSG please first download the package from:
http://technologies.kmi.open.ac.uk/msg/download.php?file=msgpackage_v2.0.zip
Then follow the instructions below. We have also produced a set of installation videos to take you through the process of installing MSG:

• Part 1: Overview and Setting up Openfire
• Part 2: Customising Openfire
• Part 3: Setting up BuddyXML
• Part 4: Testing you Installation

Package includes:

Installation Instructions

1. Install Java Runtime Environment (JRE) 5.0 (download)
2. Install Apache Tomcat 5.5 (download)
3. Install MySQL 5 (download)
4. Download MySQL Connector/J5.0 (download) and place the mysql-connector-java jar file in the tomcat\common\lib directory.
5. Create a new database in MySQL called ‘wildfire’
6. Install Openfire 3.3.1. It’s important that this particular version is used because other versions may not work. Use the links below to select the file for your platform:
   • Windows (included JRE): openfire_3_3_1.exe
   • Windows (without JRE): openfire_3_3_1.zip
   • RPM for Red Hat Linux and variants: openfire-3.3.1-1.i386.rpm
   • Works on most Unix variants, no Java JRE: openfire_3_3_1.tar.gz
   • Mac, no Java JRE: openfire_3_3_1.dmg
7. Replace openfire\lib\openfire.jar with the one from this package
8. Put openfire\lib\wildfire-extras.jar into openfire\lib\
9. Put both the files from openfire\plugins\ into openfire\plugins
10. Update openfire\conf\openfire.xml with openfire.xml from this package - you may wish to take a backup of your original openfire.xml first. You then need to edit openfire\conf\openfire.xml to point to your database, username and password.
11. Start Openfire, then in the Openfire admin page, select the HTTP Binding (under Server Settings option) and disable it.
12. Create a directory called buddyxml in \tomcat\webapps
13. Unzip the contents of the \buddyxml\BuddyXML.war into \tomcat\webapps\buddyxml
14. You will now need to edit the \tomcat\webapps\buddyxml\WEB-INF\web.xml file to check it has the following settings:

• notifier-connect-url=http://msg.open.ac.uk/buddyxml - you should replace msg.open.ac.uk with your server URL, for example http://www.mymsg.com:8080/buddyxml
• login-timeout-ms=10000
• roster-timeout-ms=30000
• max-event-queue=200

You will also need to edit the file \tomcat\webapps\buddyxml\META-INF\context.xml to point to your database, this would usually just be a case of checking the username and password attributes.

Create a directory called ‘msg’ under \tomcat\webapps\

Copy the contents of MSGClient into \tomcat\webapps\msg

You will also need to edit the file \tomcat\webapps\msg\META-INF\context.xml to point to your database, this would usually just be a case of checking the username and password attributes.

Create a directory called ‘MSGClientAPI’ under \tomcat\webapps\ROOT

Copy the contents of MSGClientAPI into \tomcat\webapps\ROOT\MSGClientAPI

The basic installation should now be complete.

Testing your installation

1. Ensure MySQL, Tomcat and Openfire are all started and running
2. Using Openfire admin pages, create a few groups and users. When creating new groups, you’ll need to ‘Enable contact list group sharing’ - this option appears after you have created the group.
3. Visit http://localhost:8080/msg and click on the Launch MSG link
4. You should now be able to log in to MSG using one of the users and password you created earlier
5. For a more ‘exciting’ test get a colleague to log in too and you should then be able to chat to each other.
6. If your installation is not working, please check our
   troubleshooting page, and if your issue is not addressed there then please contact us

MSG Moodle Block Installation

This section describes how to set up the Moodle-MSG block, to connect up to the Openfire and BuddyXML services. Please note that as MSG-Moodle block makes use of the new Moodle roles and permissions architecture, you’ll need Moodle version 1.7+ installed. We have also produced a series of videos to take you through this process:

• Part 1: Openfire and BuddyXML Configuration
• Part 2: MSG-Moodle Block Settings
• Part 3: Updating your Moodle theme

1. Firstly, you’ll need to ensure that you have a Openfire and BuddyXML service up and running correctly, see instructions above.
2. You now need to make some changes to the configuration of your Openfire and BuddyXML servers.
3. In \tomcat\webapps\buddyxml\WEB-INF\web.xml edit the moodle-url parameter to point to the root of your Moodle installation and also change the wildfire-authenticators to refer to your server e.g. www.mymsgserver.com@http://www.mymsgserver.com:9090
4. Log in to the Openfire Admin console, in the options on the left, select ’system properties’, then add three new properties as follows:

• Property name: moodle.enabled, Property value: true
• Property name: moodle.url, Property value should be set to the URL to the root of your Moodle installation
• Property name: map.service, Property value should be set to the root URL of you BuddyXML service (eg: http://myserver:8080/buddyxml)

Create a new directory in Moodle blocks directory called ‘msg’ - put all the files from MoodleBlock into this new directory. This will install the MSG-Moodle block in exactly the same way as any other Moodle block

Next, you’ll need to enter the block settings (so go to the MSG settings page in Moodle Admin area). The settings should be set up as follows:

• Title - title to appear in your block.
• QuickStart URL - link to help pages for your MSG installation - this can be left blank
• Jabber URL - URL to your BuddyXML service (e.g. http://msg.open.ac.uk/buddyxml)
• Jabber UI - URL to the user interface for your MSG server (e.g. http://msg.open.ac.uk/ui)
• Host - hostname for your MSG server (e.g. msg.open.ac.uk)
• Online user count refresh rate - how often (in millieseconds) the number of online users gets updated
• Global online cache length - how long (in seconds) the number of global users online should be cached for
• Personal online cache length - how long (in seconds) the number of personal contacts online should be cached for
• Peek timeout - how long (in milliseconds) to wait between requests to check for presence updates
• Peek timeout after interrupt - how long (in milliseconds) to wait between requests to check for presence updates if the previous peek request was interrupted. Interuption may occur if the user has MSG open in two or more browser windows, or the MSG client is open.
• Client window name - name for the MSG client browser window
• Client window properties - properties for opening the MSG client brwoser window
• Opt in/out property name - property in the mdl_user_metadata table which determines if a user has opted in or out of using MSG
• Allowed IP addresses - which IP addresses should be allowed to access the user and groups services. The IP address of your MSG server should be entered here. You can leave this field empty, in which case any IP address woul dbe allowed to access the user and groups services - but this means that all your Moodle users and groups memberships might be exposed to the world.
• Group Role ID - database ID number of the role for which you would like users to be grouped, so, e.g. if you’d like the groups to be set up on the student role, then you would enter the ID number of the student role from the table mdl_role. The reason for using ID numbers is so that multiple roles can be entered easily, to use multiple roles (e.g. teacher and student roles) then just comma seperate the ID numbers.
• Maps enabled - whether or not the Google map should displayed in the block.
• Google API Key - API key for Google maps to work, you need to obtain an API key from Google.
• Popup notification - whether a popup layer should appear when the user receives a new message.
• Textual notification - whether text should appear next to users presence icon when a new message is received.
• Popup border style - the CSS border style if the popup notification is enabled.

The next step is to add users presence icon to the Moodle header and to add the PHP code to initialise communication with the MSG server when a user visits the Moodle page. The following code should be added to your Moodle theme header.php file to import the relevant javascript and css for MSG:

<script type="text/javascript" src="<?php echo $wwwroot; ?>/blocks/msg/includes/msgconfig.js" ></script>
<script type="text/javascript" src="<?php echo $wwwroot; ?>/blocks/msg/includes/msgservice.js" ></script>
<script type="text/javascript" src="<?php echo $wwwroot; ?>/blocks/msg/includes/msgcommon.js" ></script>
<script type="text/javascript" src="<?php echo $wwwroot;
?>/blocks/msg/includes/msg.php?id=<?PHP
p($course->id);?>"></script>
<script type="text/javascript" src="<?php echo $wwwroot; ?>/blocks/msg/includes/jsr_class.js"></script>
<link rel="stylesheet" type="text/css" href="<?php echo $wwwroot; ?>/blocks/msg/includes/style.css" />


Somewhere in your header file, we’ll need to add the following code to display the current Moodle users presence icon (exactly where this goes depends on the design of your theme header):

<?php
echo '<span class="msgwidget">';
displayMSGBannerWidget();
echo '</span>';
?>


Finally, we need to update the ‘body’ tag from this:

<body<?php
echo " $bodytags";
if ($focus) {
echo " onload=\"setfocus()\"";
}
?>>

to be the following instead:

<body
<?php
require_once($CFG->dirroot.'/blocks/msg/lib.php' );
echo " $bodytags";
if ($focus){
echo " onload=\"setfocus();".initMSGBannerWidget()."\"";
} else {
echo " onload=\"".initMSGBannerWidget()."\"";
}
?>>


Now that we have the block configured and the required code in place, you can add the MSG-Moodle block to your courses either for individual courses, or as a sticky block so it appears as a block for all your Moodle courses. Once you have added the block to a course you can see that the block is working if your presence icon in the header has gone green and you can use the ‘Launch MSG’ link from the Moodle block.

If you have any problems getting the MSG-Moodle block to work correctly, please see our website.

Optionally, once you have the basics running, you may want to further integrate MSG into Moodle, by having users presences displayed in other parts of the Moodle site. For example, you may want to show users MSG presence status in the Moodle forums. To do this you can make use of the PHP function “display_jabber_state”. To use this add the following line to the top of the Moodle PHP page:

require_once($CFG->dirroot.'/blocks/msg/lib.php');


This will include the MSG PHP library. Then you can use

display_jabber_state($userid,false);


whereever you would like the presence state displayed. The first parameter ($userid) is the ID of the user you want to display the presence state for and the second parameter (a boolean value) determines whether or not to show the presence state in text format next to the presence icon. The presence state will only be displayed for uses who have opted in to using MSG and who share a course with the current user (i.e. both users must have at least one course enrolment in common).