WebCalendar System Administrator's Guide

Document Version: $Id: WebCalendar-SysAdmin.html,v 1.3 2003/07/17 18:19:50 cknudsen Exp $
WebCalendar Version: 0.9.41

Table of Contents

Introduction

WebCalender is an open source PHP-based multi-user calendar.

Features:

System Requirements

Recommended:

You must have one of the following databases installed:

For the database you choose, you must have its drivers built into PHP. For example, to use MySQL, PHP must be compiled with MySQL support (which is the default setting when installing PHP). See the PHP pages (www.php.net) for more information on setting up PHP.

No optional PHP packages (other than MySQL) are required for this application. However, PHP shoud be compiled with --enable-track-vars on some systems.

Make sure that magic_quotes_gpc in php.ini is turned on (otherwise, you will get database errors when entering quotation marks in HTML forms).

You can run PHP either as a CGI or an Apache module. You'll get better performance with PHP setup as a module. Not only will you not have to deal with the CGI performance hit, but you'll be able to use PHP's database connection pooling. Additionally, this application can use a form/cookie-based authentication or traditional HTTP authentication. For traditional HTTP authentication, PHP must be built as an Apache module.

If you are planning on using email reminders, you will need to build PHP as a CGI in order to run the send_reminders.php script. I would strongly recommend building a module-based PHP for your web server and then a second PHP build to create the CGI version.

TIP: Some Linux distributions come with both a module-based PHP with Apache and a standalone PHP binary. Check for /usr/bin/php to see if you already have the PHP standalone executable. If it's there you can use the following command to see what version of PHP you have:

/usr/bin/php -v

File Unpacking

Unpack the calendar software in its own directory somewhere where your web server will find it. (See your web server docs for info.)

By default, WebCalendar should create its own directory when you unpack it. The new directory name will typically contain the version name (such as WebCalendar-0.9.41). You can rename this directory after unpacking the files if you prefer a directory name like calendar or webcalendar. Keep in mind that unless you remap the directory (via your web server's configuration settings), it will be part of the URL for the calendar.

Database Setup

There are three steps in setting up the database:

  1. Creating the database
  2. Creating the user
  3. Creating the required tables

Follow the steps outlined below for the database you are using. When complete, a single user account will be created with the login "admin" and password "admin", which you are encouraged to use to create your own account.

Note: In the examples below, text in bold represents text that you must type in.

MySQL

The following will create a database named "intranet".

mysqladmin create intranet

Next, create the database user account that will be used to access the database.

mysql --user=root mysql
mysql> GRANT ALL PRIVILEGES ON *.* TO webcalendar@localhost IDENTIFIED BY 'webcal01' WITH GRANT OPTION;
mysql> FLUSH PRIVILEGES;
mysql> QUIT

If you will be accessing MySQL from a different machine than the one running the web server, repeat the command above and replace 'localhost' with the hostname of the other machine.

Create the calendar tables using the supplied tables-mysql.sql file:

mysql intranet < tables-mysql.sql

In the above example, "intranet" is the name of your database.

Oracle

The following will create a tablespace named "webcalendar". From the command line, startup sqlplus and issue the following command:

sqlplus
SQL> CREATE TABLESPACE webcalendar DATAFILE 'webcalendar.dat' SIZE 10M AUTOEXTEND ON NEXT 10M MAXSIZE 40M;

Next, create the database user account that will be used to access the database.

sqlplus
SQL> CREATE USER webcalendar IDENTIFIED BY webcal01 DEFAULT tableSPACE webcalendar;
SQL> GRANT dba TO webcalendar;
SQL> quit

Create the calendar tables using the supplied tables-oracle.sql file:

sqlplus webcalendar/webcal01
SQL> @tables-oracle;
SQL> quit

PostgreSQL

The following will create a database named "webcalendar". From the command line, startup psql and issue the following command:

create database webcalendar;
\c webcalendar
\i tables-postgres.sql
\q

Interbase

The following will create a database named "WEBCAL.gdb". From the command line, startup usql and issue the following command:

CREATE DATABASE 'WEBCAL.gdb';

Create the calendar tables using the supplied tables-ibase.sql file:

isql
connect /path/WEBCAL.gdb;
input path/table-ibase.sql;

ODBC

Setup will depend on which database you are using. When it comes time to create the tables, the tables-postgres.sql file should work for most databases.

Application Setup

Next, you will need to customize the file includes/config.php to tell WebCalendar which database you are using and what the database login/password is. Use your favorite text editor (vim, emacs, notepad, etc.) to make these changes.

To configure your database access. Set the values for:

$db_type One of "mysql", "oracle", "postgresql", "odbc", or "ibase"
$db_host The hostname that database is running on. (Use localhost if it's the same machine as the web server.) (This variable is not used with ODBC)
$db_login The database login
$db_password The database password for the above login
$db_database The name of the database that the calendar tables reside in. ("intranet" in the examples above.) For ODBC, this should be the DSN.

You can configure the calendar to run in single-user* mode or multi-user* mode. If this is your first time using the calendar, it's easier to try single-user. You can always switch to multi-user later. Leave $single_user set to "N" (the default) for multi-user or set it to "Y" and set the value of $single_user_login to a login name of your liking to set the system to single-user mode. (And be sure to set the value of $single_user_login to the login that you would choose if you decide to switch to multi-user mode some day.)

Note: If you do decide to switch from single-user mode to multi-user mode, make sure you add in a user to the system for the login you set the $single_user_login variable to. You will need to do this via the database (mysql, sqlplus, etc...) Look in the tables-mysql.sql (or tables-oracle.sql, etc.) to see the example of adding in the "admin" user.

If you are setting up a multi-user calendar, you will need to choose how your users are authenticated. You must change the settings of $use_http_auth and $user_inc within the config.php configuration file to setup which authentication method to use.

You currently have four choices:

  1. Web-based authentication (login/passwords verified in the WebCalendar database):
    $use_http_auth = false;
    $user_inc = "user.php";
  2. HTTP-based authentication (login/passwords verified by the web server):
    $use_http_auth = true;
    $user_inc = "user.php";
    ... and don't forget to setup your web server to handle user authentication.
    Note: In order to use HTTP-based authentication, PHP must be setup as a module for your server rather than a CGI.
  3. NIS-based authentication (login/passwords verified by NIS):
    $use_http_auth = false;
    $user_inc = "user-nis.php";
    Additional configuration settings will need to be set in includes/config/user-nis.php.
  4. LDAP-based authentication (login/passwords verified by LDAP server):
    $use_http_auth = false;
    $user_inc = "user-ldap.php";
    Additional configuration settings will need to be set in includes/config/user-ldap.php.

Keep in mind that if you want to use reminders, you will need to setup the send_reminders.php script (see below) and keep your admin setting for "Email enabled" set to "Yes" on the admin settings page.

Setting Up Email Reminders

PHP does not come with a utility for executing time-based jobs. So, in order to check periodically for email reminders, a shell script was written in PHP. You will need two things to get this working:

  1. You should have a version of PHP built as a CGI (so that you can run php from the command line). This does not mean you must build all of PHP as a CGI. You can still build PHP as a module for your web server and then build the CGI-based PHP later. Note: Many Linux distributions and some Windows LAMP packages come with the PHP built for CGI.
  2. You must setup cron (on Linux/UNIX) or something like cron for Windows to run the send_reminders.php script periodically.

Building PHP as a CGI is outside the scope of these instructions. But, if you read the PHP instructions, you'll see that the default build settings will build the CGI-based PHP. If you really can't do this (perhaps you don't have permission to install anything new on the system), skip down a couple of paragraphs to an alternate solution that does not require PHP CGI.

For Linux/UNIX users, add the following line to the crontab entry of a user. (This would be the same user that the web server process runs as.)

1 * * * * cd /some/directory/webcalendar/tools; ./send_reminders.php

Of course, replace the directory location to wherever the send_reminders.php file can be found. If you moved this out of the tools directory (which is recommended for security reasons), be sure to update send_reminders.php since it needs to know where to find other WebCalendar files.

If you cannot setup PHP as a CGI or have no idea how, you can leave send_reminders.php in its current location and access it via a URL. IMHO, this is not the best choice, but it still works. Setup a cron job to access the URL. For Linux/UNIX users, add the following line to the crontab entry of a user.

1 * * * * wget http://yourserverhere/webcalendardirectoryhere/tools/send_reminders.php > /dev/null

You should test this from the command line first to make sure your setup is correct. If you do not have wget installed on your system, you can use any tool (lynx, perl script, etc.) that is capable of making an HTTP request for this.

System Settings

System Settings allows the administrator to control what features are available to users as well as default values for certain features.

Many of these settings can be overridden by users in their Preferences (such as color).

Settings

Application Name
Specifies the document title (typically displayed in the window title bar of most browsers)
Server URL
Specifies the base URL of the calendar. This information is needed to accurately include URLs in email messages (Notifications and Reminders).
Language
Specifies the default language setting for all users.
Fonts
Specifies your preferred font. Multiple font names should be comma-separated.
Preferred View
Specify if users should see the day, week, month, or year after loggin in.
Display weekends in view
Specifies default setting for if Saturdays and Sundays should appear in the calendar when viewing a month or week
Date format
Specifies the default format for displaying dates
Time format
Specifies the default time format as either 12-hour (3:45pm) or 24-hour (15:14)
Time interval
Specify the default number of minutes each time block represents in the day and week display
Auto-referesh calendars
If set to "yes," the day, week, and month pages will automatically reload after a specified duration
Auto-refresh time
Specifies how long to wait before the auto-refresh should force a page to be reloaded
Display unapproved
Specifies whether events that have been added to a calendar but not yet approved should display on the calendar (in a different color)
Display week number
Specifies whether the week number should be displayed in month and week views
Week starts on
Specifies if week start on Sunday or Monday
Work hours
Specifies the default time range to display in day and week views
Disable Priority field
If enabled, the Priority field will not be used
Disable Access field
If enabled, the Access field will not be used
Disable Participants field
If enabled, the Participants field will not be used, and users will not be able to add events to any calendar other than their own.
Disable Repeating field
If enabled, users will not be able to create repeating events
Allow viewing other user's calendars
If enabled, users will be able to view the calendar of another user
Allow public access
If enabled, anonymous users will be able to view the public access calendar without logging in.
Public access can view other users
If enabled, anonymous users will be able to view the calendars of other users
Public access can add events
If enabled, anonymous users will be able to submit new events.
Public access new events require approval
If enabled, events submitted to the public access calendar (by anonymous users) will require approval by an admin user. If not enabled, then new events will appear on the public access calendar as soon as they are submitted.
Include add event link in views
If enabled, Views will include a link to quickly add events to the specified user's calendar.
Allow external users
If enabled, the create/edit event page will contain a text area to include the names (and optional email address) of event participants that are not calendar users.
External users can receive email notifications
If enabled, event participants entered into the External Participants area will receive email notifications at the same time as calendar users (if an email address was specified for the Exernal Participant).
External users can receive email reminders
If enabled, event participants entered into the External Participants area will receive email reminders at the same time as calendar users (if an email address was specified for the Exernal Participant).
Remember last login
If enabled, when a returning calendar user reaches the login page, their login name will be pre-filled with the last login username that they entered. (The password field will still be blank.)
Check for event conflicts
Specifies if the system should check for scheduling conflicts when a user adds or updates an event.
Conflict checking months
If conflict checking is enabled, this specifies how many months past the initial date the system will check for conflicts when a user adds or updates a repeating event.
Allow users to override conflicts
If enabled, users will be warned when there is an event conflict and be presented with the option of scheduling the event anyhow.
Limit number of timed events per day
If enabled, users can can be limited to a specific number of timed events per day
Maximum timed events per day
Specifies that maximum number of events that can be scheduled in one day of any one user.

Groups

Groups enabled
Specifies if group features should be enabled
User sees only his group
If enabled, users will be unaware of any users that are not in the same group as the user.

Categories

Cagtegoies enabled
Specifies if category features should be enabled

Email

Email enabled
Specifies if email functionality should be enabled. If set to "No," then no email messages will be sent at any time.
Default sender address
Specifies the email originator to use when the system sends out email Notifications and Reminders
Event reminders
Specifies if email reminders for events that include a reminder should be sent
Events added to my calendar
Specifies if the system should send email when an event is added
Events updated on my calendar
Specifies if the system should send email when an event is updated
Events removed from my calendar
Specifies if the system should send email when an event is deleted
Event rejected by participant
Specifies if the system should send email when a participant to an event rejects the event

Colors

Allow user to customize colors
Specifies whether color settings should be available to users in their Preferences
Document background
Specifies the background color of all pages
Document title
Specifies the color of page title on each page
Document text
Specifies the default text color on each page
Table grid color
Specifies color of the lines that make HTML table grids on each page
Table header background
Specifies the default background for the heading of any HTML table
Table header text
Specifies the default text color for the heading of any HTML table
Table cell background
Specifies the background color for table cells
Table cell background for current day
Specifies the background color for the table cell containing the current date
Table cell background for weekend
Specifies the background color for table cells that represent a Saturday or Sunday
Event popup background
Specifies the background color of event popup areas
Event popup text
Specifies the text color of event popup areas

Custom Event Fields

You may want to customize the event-specific fields found in the includes/site_extras.php field. If this is your first time using the calendar, you can skip this step and come back later since this step is optional.

You can use this feature to add extra fields to your calendar events. For example, you can add a URL, a contact email address, or a location.

By default, this file is configured with a single reminder field that allows the user to specify how long before the event the reminder should be sent.

TIP: See instructions on setting up reminders to enabled reminders to be sent.

When defining a new custom field, the following types listed below are available. "Arg 1" and "Arg 2" have different meaning depending on the type of field. In some cases, "Arg 1" and "Arg 2" are not used.

TypeDescriptionArg 1Arg 2
EXTRA_TEXT Allows the user to enter a single line of text Specifies the size of the text form element as it would appear in the following ("NN" would be replaced with Arg 1):
   <input size="NN" ...		 N/A
EXTRA_MULTILINETEXT Allows the user to enter multiple lines of text Specifies how many characters wide the textform element should be as it would appear in the following ("NN" would be replaced with Arg 1):
   <textarea cols="NN" ...		 Specifies how many lines long the textform element should be as it would appear in the following ("NN" would be replaced with Arg 1):
   <textarea rows="NN" ...
EXTRA_URL Allows the user to enter a single line of text and will be displayed as a link when viewed N/A N/A
EXTRA_DATE Allows the user to select a date using the standard date selection form elements N/A N/A
EXTRA_EMAIL Allows the user to enter a single line of text and will be displayed as a mailto URL link N/A N/A
EXTRA_REMINDER Allows the user to specify if a reminder should be sent out for the event Specifies how many minutes before the event that the reminder should be sent. Specifies other reminder-specific options. The following options are available:
  • $EXTRA_REMINDER_WITH_DATE
  • $EXTRA_REMINDER_WITH_OFFSET
  • $EXTRA_REMINDER_DEFAULT_YES
If more than one option is needed, they should be or-ed together with the | character.
EXTRA_REMINDER_DATE Allows the user to specify if a reminder should be sent out for the event and and what time it should be sent Specifies the default for how many minutes before the event that the reminder should be sent. The user can override this when they create/edit the event. Specifies other reminder-specific options. The following options are available:
  • $EXTRA_REMINDER_WITH_DATE
  • $EXTRA_REMINDER_WITH_OFFSET
  • $EXTRA_REMINDER_DEFAULT_YES
If more than one option is needed, they should be or-ed together with the | character.
EXTRA_SELECTION_LIST Presents the user with a selection list to choose from Specifies the list of available options using the PHP array function N/A

Frequently Asked Questions

How do I setup PHP, MySQL and Apache on Windows?
The easiest way to do this is to try one of the prepackaged bundles that will install all of these for you:
How do I setup PHP, MySQL and Apache on UNIX/Linux?
There are many online instructions on how to do this. Here are a few:
I've finished the install. What is the login to WebCalendar?
After the initial creation of the database tables, there will be a single user account created with the username "admin" and the password set to "admin" as well.
Note: This account is intended to get your started. You should create a new admin account and delete this one.
I want to use WebCalendar as an events calendar for my organization. How do I set it up to do this?
You will want to setup WebCalendar to use public access.
  1. Setup your config.php file as a multi-user system (see instructions).
  2. In System Settings, set "Allow public access" to "Yes."
  3. If you want people to be able to submit new events through public access, set "Public access can add events" to "Yes."
  4. If you set "Public access can add events" to "Yes", set the setting for "Public access new events require approval" to your liking. If you set this to "Yes," an admin user will need to approve any new events before they will appear on the public access calendar.
  5. Login using one of the accounts you have setup. Add a new event, and select "Public User" as one of the participants.
  6. If you have enabled "Require event approvals" in your System Settings, then you will need to approve the new event. Choose the "Unapproved Events" at the bottom of any page (you must be an admin user to access this). You will be presented with a list of unapproved events (for both the current user and for the Public User account). Approve the new event for the Public User.
  7. Go to the Login page. You will see a "Access public calendar" link that will bring you to the calendar for public access.
  8. By default, the index.php page should send users to the public calendar.
Why are deleted events still present in the database?
When you delete an event from your calendar, it is not deleted from the database. Instead, it is marked as deleted. This allows the system administrator access to information even after it is deleted.

Troubleshooting

I get error messages about undefined variables when I try to view any page.
On newer versions of PHP, the default setting of PHP is to display messages when an undefined variable is referenced. To prevent these messages from being displayed, change the setting of error_reporting in your php.ini file to be:
error_reporting = E_ALL & ~E_NOTICE
Alternately, you can disable any error messages from being displayed in the browser and have them logged to a file. (See the comments included in the php.ini file for instructions on how to do this.)
I get errors when trying to add an event that contains a single quotation.
WebCalendar is designed to work with PHP's magic_quotes_gpc feature (configured in php.ini). If you do not have this enabled, you may get errors when adding events.
I get an error message from PHP saying "Call to undefined function: ..."
This tells you that your version of PHP is missing something that WebCalendar needs. If the function mentioned is a database login function ("ociplogin", "mysql_pconnect", "ibase_connect", "pg_pconnect"), then you probably do not have the needed database support for your database compiled into PHP. If the function is not a database connect call, then check the PHP manual to see if the function requires a specific version of PHP. You may have an out-dated version of PHP that requires upgrading.
When I try and view certain pages, nothing happens for 30 seconds, then I get a time-out error.
On slower or very busy servers, it can take some time for the server to get all the events. Most PHP installations have a built-in timeout out of 30 seconds and will interrupt any request that takes longer than that. This is most likely to happen on the year-long custom report or on the month view when layers are being used. If you have access, you can increase the time-out value for PHP in the php.ini file by changing the setting of the max_execution_time setting.
I am not receiving any email messages from WebCalendar.
WebCalendar sends two types of email messages: Notifications* and Reminders*. Check the following if you are not receiving any email:
  1. You have defined a valid SMTP server in your PHP configuration file php.ini. (The setting is "SMTP" in the "mail_function" section.
  2. In WebCalendar's System Settings, you have set the "Email Enabled" setting to "Yes".
  3. In WebCalendar's System Settings, make sure you have the "Default sender address" to something.
    Note: Some mail system will reject mail that has a "From" address that is a different domain from the originating SMTP server. So, if your SMTP server is smtp.mydomain.com and your "Default sender address" is calendar@someotherdomain.com, some mail systems may bounce the mail back.
  4. For a Notification, make sure you have the type of Notification set to "Yes" in the user's Preferences.
  5. For a Reminder:
    • Make sure you have "Event reminders" set to "Yes" in the user's Preferences.
    • Make sure you have setup a cron job to periodically run the send_reminders.php script.
Some of the pages are displaying text in English rather than <insert your language here>
The translations have been submitted at various points of WebCalendar development. Some have not been updated to include newer features.
The text that I entered in the Custom Event Fields is not being translated to different languages.
You will need to add an entry in each of the translation files for any text you add into the Custom Event Fields.
How do I get the most recent version of WebCalendar?
You can download the latest public release from SourceForge's file list for WebCalendar.
You can download the latest development code from the CVS server using the the instructions provided by SourceForge. (You will need a CVS client to do this.)
How do I install a patch file listed on SourceForge's list of WebCalendar patches?
Most patches are distributed as context diffs. That means they were produced using the UNIX diff command with the -C option. The patches are intended to be used with the GNU patch program. This program is standard on most Linux systems and can be obtained as part of the Cygwin package for Windows. Mac OS X will have the patch program installed if they install the developer tools CD.

Getting Help

Try the Help/Troubleshooting forum for WebCalendar, hosted at SourceForge.net:

http://sourceforge.net/forum/?forum_id=11588

If you encounter a bug, please check the list of open and pending bugs. If you do not see anything similar, submit a new bug.

Licensing

WebCalendar is distributed under the open source GNU General Public License. If you have questions about this license, please read their GPL FAQ.

Glossary

Activity Log
A summary of recent updates to calendar data
Assistant
A calendar user that has been designated by another calendar user (the Boss) to help manage their calendar
Boss
A calendar user that has designated another calendar user (the Assistant) to help manage his calendar
External User
A calendar participant that does not have a calendar user account
Group
A mechanism of dividing up a large set of users into smaller sets of users
Layer
A function that allows a user to overlay another user's calendar on top of his own calendar so that the standard day, week and month pages show both his own and the layered user's events
LDAP
LDAP (Lighweight Directory Access Protocol) is an Internet protocol used to maintain user directories
Multi-User Mode
When WebCalendar is configued in Multi-User Mode, there can be multiple user accounts, each with his own calendar. Unless Public Access is enalbed, all users will be required to login before they can access the system.
NIS
NIS (Network Information Service) is a UNIX-based user authentication system for managing user directories in a network
NonUser Calendar
A participant to a calendar event that is not a calendar user
Notification
An email message that is sent when an event is added, removed or updated in the user's calendar by another user
Preferred View
The standard page (day, week, month or year) that will be presented to the user after logging in (set in user Preferences)
Public Access
A System Setting that will allow anonymous users to access the calendar. See the simple instructions for setting this up in the FAQ section. (Required WebCalendar to be configued in Multi-User Mode).
Reminder
An email message that is sent before an event to remind the participant
Single-User Mode
When WebCalendar is configued in Single-User Mode, there is no concept of users. You will be managing a single calendar and no login will be required. Anyone accessing this calendar will have full privileges to view, add, edit and delete all events.
Time Interval
The amount of time each "block" will represent in either the day or week view (set in user Preferences)
View
A customized page that presents the events of selected users
Work Hours
The default hours to show in the week and day view where events are displayed in blocks of time (set in user Preferences)

History

$Log: WebCalendar-SysAdmin.html,v $
Revision 1.3  2003/07/17 18:19:50  cknudsen
Added more to FAQ.

Revision 1.2  2003/07/17 17:52:44  cknudsen
Added to FAQ: issued with undefined variables

Revision 1.1  2003/06/26 17:52:44  cknudsen
First draft