Installation

This page describes the minimal number of steps necessary to get the iGroupCal servlet up-and-running on an existing Tomcat server. There are a few other things you can do if you want to dig around in the servlet config file, but I'm not going to get into them (yet).

Since the primary use of iGroupCal (for me anyway) is to work together with Outlook® users on Windows®, this setup description is for Tomcat running on a Windows PC. Tomcat is fortunately quite platform-agnostic, so you should be able to transfer any information here to MacOS X or Linux.

In the descriptions below, ${CATALINA_BASE} refers to the directory in which you have installed the Tomcat server. On a Windows PC, this could be something like C:\Program Files\Apache Software Foundation\Tomcat 5.0.

  1. Make sure you have a working installation of Apache Tomcat. Setting up Tomcat is beyond the scope of this document, but you'll need to get it running before going any further. Make sure you can log in to the "manager" and "admin" servlets.

    iGroupCal was developed using Tomcat 5.0.28 but iGroupCal works fine with the 5.5.x version as long as you're using Java 5/1.5.

  2. Decide which database you're going to use. If you're using Group Calendar from OpusFlow, you should already have a database set up:

    - If you're using Access® you'll need to set up an ODBC System DSN which references the .mdb file. The iGroupCal servlet config file example configuration for the Access driver uses a DSN of "GroupCal".

    - If you're using MS SQL Server®, you'll need to make sure you have an appropriate read/write user login to use with iGroupCal. In addition, this would be a good time to download the MS SQL Server JDBC drivers (see the utilities page).

    If you don't have Group Calendar please have a look at the FAQ page and set up an appropriate database.

  3. Set up the Tomcat users file for iGroupCal authentication. You can find a sample file, igroupcal-users.xml in the server-config directory of the .war file you downloaded, or you can download the file directly - igroupcal-users.xml.

    Place the file somewhere accessible to the Tomcat server; I put mine in ${CATALINA_BASE}/conf.

    Remember this location for the next step. Enter all the usernames and passwords for the users you want to have access, and decide if you want to have a special read-only user (one is included in the file by default, so you'll have to delete it if you don't want it).

  4. Set up a Tomcat authentication database for iGroupCal. This should be done before you deploy the .war file - otherwise the the servlet will not be loaded properly and you will get an exception message when you try to deploy the servlet.

    You have two options to do this:

    1. Modify the Tomcat server.xml file by hand. In the server-config directory of the .war file, there is a server.xml file which contains the necessary modifications. Merge these modifications with your server.xml file.

      2. or

    2. Use the "admin" servlet to create a UserDatabase.
      Log on to your server and fire up the "admin" servlet. If you're working on the server console, this should be something like http://localhost:8080/admin.
      Click on the UserDatabase node in the tree. Select "Create New User Database" from the drop-down menu top right. Enter the information as shown in the image at right. (Essentially, the User Database must be called iGroupCalUserDatabase, and must point to a Tomcat-style users file). If you do not have this set up, you will most likely see an exception when you try to start the servlet. User DB
      Click "Save" once you've entered the information. You should get a screen which looks like the one at right. Click on the "Commit Changes" button top-right. User DB done

  5. Deploy the igroupcal.war file. You can do this manually, which gives you a lot more flexibility in where files go on your system, or you can use the "manager" servlet. I'm only going to describe the "manager" version, since I assume that if you care about doing it manually you'll take the time to learn from the Tomcat web site.

    Fire up the "manager" servlet. If you working on the server console, the address should be something like http://localhost:8080/manager/html. Scroll down until you see the "WAR file to deploy" form, and browse to where you saved the .war file. Click on "Deploy" and you should be good to go. Deploy WAR
    Once you've clicked deploy, the message bar at the top should read "OK" and you should be able to see the iGroupCal servlet (listed as "/igroupcal") in the listed of active servlets. If not, it means the servlet could not be started and it's probably time for you to start digging in your log files for the reason why... Deploy WAR

  6. Set up the DB access according to your system. This is accomplished by editing the web.xml file for the iGroupCal servlet. If you have used the "manager" servlet to deploy, you will find this file in ${CATALINA_BASE}/webapps/igroupcal/WEB-INF.

    The section of the web.xml file you need to edit looks something like this:

    <!-- -->
<init-param>
	<param-name>jdbcDriver</param-name>
	<param-value>com.microsoft.jdbc.sqlserver.SQLServerDriver</param-value>
</init-param>
<init-param>
	<param-name>jdbcURL</param-name>
	<param-value>
		jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=igroupcal
	</param-value>
</init-param>
<init-param>
	<param-name>jdbcUser</param-name>
	<param-value>gcuser</param-value>
</init-param>
<init-param>
	<param-name>jdbcPassword</param-name>
	<param-value>gcuser</param-value>
</init-param>
<init-param>
	<param-name>dbFieldFile</param-name>
	<param-value>gcfields-mssql.xml</param-value>
</init-param>
<!-- -->

    The web.xml file contains sample sections for using Access via ODBC, Microsoft SQL Server, MySQL, and PostgreSQL servers. Adjust the jdbcURL, jdbcUser, and jdbcPassword parameters to match the settings you need for your server.

    If we work through the default setup for an SQL Server database, you will notice that the interesting part of the jdbcUrl parameter looks like this: 

    localhost:1433;DatabaseName=igroupcal

    In this case, localhost is the server name, 1433 is the port number on which SQL Server is listening for remote connections, and the database on the server is named igroupcal. Adjust these to match your installation. (The default for an OpusFlow Group Calendar installation is to use a database named GroupCalendar).

    You will also have to provide a read/write username and password for a user who has access to your iGroupCal databased. I have set up a special user gcuser with the password gcuser to use with the iGroupCal database. Put your username and password parameters in the jdbcUser and jdbcPassword parameters respectively.

    If you are using an Access database, you should comment out the MS SQL section and uncomment the Access section. Check that last part of the jdbcURL parameter matches the ODBC System DSN you set up earlier. You shouldn't need a username or password.

    For all the other non-Access DB servers, the process is similar. Determine the correct URL, username, and password for remote access to your server. if you are getting an exception message in the log that looks like this:

    [GCDBReader_Preload-1][processDB] Caught Exception in processDB: Can't access database:
        com.mysql.jdbc.Driver
        => (jdbc:mysql://localhost:3306/igroupcal)
        => (gcuser)
        => (gcuser)

    I would recommend that you try to connect to the database using the standard database management tools such as MS Query Analyzer, mysql, or psql using the username and password shown in the last two lines of the exception message (these should be the same as you configured in the web.xml file.

  7. Configure any remaining parameters in the web.xml file. Probably the only really relevant parameter (beyond tweaking or testing) is the timezone value. By default it is set to "Europe/Zurich", which is where I live but you probably don't. This value controls which timezone igroupCal uses when it creates the group calendar, and determines how it will interpret appointments from other timezones.

    You can erase "Europe/Zurich", leaving the value blank, and iGroupCal will use the default Java timezone based on how your computer is set up. In my case however, this meant that my timezone was reported as "Europe/Berlin" which is okay from a time point of view, but leads to confusion when you look at appointments in iCal.

    A decent reference for available timezone codes can be found at www.timezoneconverter.com .

  8. If you want, set up a user name to owner name mapping. For example in the igroupcal-users.xml authentication file, my login is "WH", but if I wanted my entries to appear in the group calendar as "Will Harris" I'd make an entry in ${CATALINA_BASE}/webapps/igroupcal/user-owner-map.xml. (This filename is controlled by the userOwnerMapFile parameter, but I can't see why you'd want to change it...).

    An entry is this file looks like

    <groupcaluser user="WH" owner="Will Harris"/>

    Feel free to add as many mappings as you like. If a user name is not found in this file, the user name (e.g. "WH") is used for displaying the subjects in the group calendar.

  9. Try publishing a calendar and subscribing to the Tomcat server (see the screenshots for some more detail about doing this) to check that everything works as expected.

    Bear in mind that the idea of iGroupCal is to aggregate calendars into one single calendar. If you publish three calendars "Dog", "Cat", and "Mouse" you will not be able to subscribe to those individual calendars - even if you use the URL given iCal as the subscription URL you will still get the sum of all three calendars. Don't be confused, this is the way it's supposed to be!

  10. Crack a cold frosty beer, 'cause that was hard work.

If, even after this incredibly detailed and exhaustive installation guide, you find that something's not working properly, drop me a line at

You need JavaScript to see this email address!

.