Description of General System FunctionalityphpScheduleIt was developed for reservation and resource management. This includes a full user log in and registration system, user profile management, the scheduling/reservation system, and numerous administration tools. The entire system was written using PHP 4.3 by Nick Korbel. The system uses any PEAR supported database to store and manage all user, resource and reservation information. Because of the availability of PHP, this system will run on any platform that meets the aforementioned necessary requirements. At the time of writing, the currently supported PEAR databases are: dbase, fbsql, interbase, informix, msql, mssql, mysql, oci8, odbc, pgsql and sybase (DB style interfaces to LDAP servers and MS ADO (using COM) are also availed from a separate package). The system is optimized for Internet Explorer 5.5 or greater, Netscape 6.x or greater and Mozilla 1.0 or greater. Netscape 4.7 is not supported. Any questions or bug reports should be directed to Nick Korbel at lqqkout13@users.sourceforge.net Requirements- PHP 4.3 or higher (4.2.x is supported but not recommended) Installation/SetupSetup can be accomplished by using the included setup script (setup.php) or manually, by following the instructions below. Note: Many of these steps include syntax that may or may not be exclusive to MySQL. Please consult your database manual for other database syntaxes. 1) Verify that the PEAR DB package, a PEAR supported database (view currently supported databases) and PHP version 4.2.0 or greater are installed and properly configured on the destination server. If not, download and install at least these versions. 2) Copy all of the phpScheduleIt files provided into a desired web directory. Remember this directory because we will need it in the next two steps. 3) Edit your config/config.php file to be sure it is correct for your web server set up. Most importantly, make sure that the 'weburi', 'dbType', 'dbUser', 'dbPass' and 'dbName' settings are correct. Automatic setup -1) Simply run the install script by navigating your browser to http://yourwebsite.com/path_to_phpscheduleit/install/setup.php. You will be asked for your database password. 2) You will receive a confirmation or rejection notice about each command being executed. If everything goes well, you will receive a final notice that the installation was successful. 3) DELETE THE 'INSTALL' DIRECTORY. This is a critical step. If the directory is left, then anyone is open to destroy your newly created database. Manual setup -1) The initial database must now be set up. There is an included setup file for this. If you want to change the default user and password to be used for the schedule database, first edit the setup.sql file (please refer to your database's manual for more on how to accomplish this), then execute it. To execute the setup file in mysql, navigate to the MySQL executable directory (usually /usr/local/mysql/bin) and at the shell prompt type the following: mysql -u root -p < %path to directory%/install/setup.sql For example: mysql -u root -p < /www/htdocs/php/scheduler/setup.sql You will be prompted to enter the root MySQL password at this point. This script will create the schedule database, the schedule user/password combination and grant specific privileges to that user. For syntax for other databases, please consult your manual. 2) Verify the installation was successful by bringing up the MySQL Monitor (typing mysql at the shell prompt). Please note that all commands entered in the MySQL Monitor end with a semicolon. At the mysql prompt, type show databases;. You will be informed that the database has been changed. If the database that you just created is listed, then the installation was successful. Type quit; to exit the MySQL Monitor. 3) From the phpScheduleIt directory (%path to directory%), DELETE THE 'INSTALL' DIRECTORY. 4) Open the config.php file and immediately change the administrative login ($conf['app']['adminEmail']) from its default to a new desired login. 5) If desired, change any other settings in the configuration file. Multiple Database Setup -To set up the system to use multiple databases (for example sharing a login table), first make sure that the tables that you want to use from a different database are already running. Next, set up a new version of phpScheduleIt by following either the Automatic or Manual Setup instructions above. Next, edit the config/config.php file. Find the 'pk_prefix' field and change it to something that no other instance of the scheduler is using. Now, you will need to edit the lib/DBEngine.class.php file. This is where all the database names to be used are defined. In the DBEngine() function, find the line that starts with "$this->dbs = array (xxxx);" For each additional database that you want to associate with this version phpScheduleIt, add a comma and then the name of the database, in single quotes. For example, to use 2 databases the line would look like this: $this->dbs = array ($GLOBALS['conf']['db']['dbName'], 'name_of_database2'); Further down, find function define_tables(). This is where the table/database relationships are defined. For each table, assign a database that it comes from. This can be done by counting, in order from 0, the number that the database you want to associate a table to, and typing that between the brackets on the same line as the table name. For example, to use the default database for the login table, but 'name_of_database2' for the rest of the tables, your code would look like this: $this->table_to_database = array ( 'login' => $this->dbs[0], 'reservations' => $this->dbs[1], 'resources' => $this->dbs[1], 'permission' => $this->dbs[1] ); Be sure that you do not change the table names, only the number between the brackets. Upgrading From version 0.9.0If you want to upgrade from version 0.9.0, please modify the two database variables and run install/update/0.9.0_to_0.9.3.php. This file will update the database schema to the one that is used in the stable release and keep all of your data. At the top of this file, there are two variables; root_user and root_password. Please set these to the database root user who has permission to modify and delete databases. Note: You can keep your current config.php file. All the variables are the same and this file will be compatible with version 0.9.3. Your application will report that you are using phpScheduleIt 0.9.0, though. Please refer to the release notes in the install directory for any additional information. Configuration FileApplication SettingsAll of these settings apply to how the application functions. $conf['app']['weburi'] This is the full URL to the base directory of phpScheduleIt (where index.php resides). For example, if you installed it in htdocs/phpscheduleit, the value would be http://www.yoursite.com/phpscheduleit. Please do not include the trailing slash on this value $conf['app']['startDay'] This is the starting time of when reservations can be placed. No reservations can be placed before this time. This value must be in 24 hour time (midnight is 0). Specify half hours with .5. For example, if the day started at 8:30 am, this value would be 8.5. If it started at 9:00 am, it would be 9.0. Value range is from 0 to 23.5. $conf['app']['endDay'] This is the ending time of when reservations can be placed. No reservations can be placed after this time. This value must be in 24 hour time (midnight is 24). Specify half hours with .5. For example, if the day ends at 8:30 pm, this value would be 20.5. If it ends at 9:00 pm, it would be 21.0. Value range is from 0.5 to 24. $conf['app']['timeSpan'] This is the minutes between each time interval on the scheduler. For example, half an hour is 30, an hour is 60, an hour and a half is 90. Consequently, this will also be the minimum reservation length for all resources. This number must divide evenly into your day length. To see if the value is acceptable, use this equation ((endDay - startDay) * 60)/timeSpan. If there is no remainder, this value is acceptable. The acceptable values for this setting are 15, 30, 60, and anything over 60 that divides evenly into your day length. $conf['app']['timeFormat'] This is the format to view the times in. A value of 12 means that dates and times will be on the 12 hour clock (using am/pm). A value of 24 means that dates and times will be on the 24 hour clock (no am/pm). Only 12 and 24 are accepted values. $conf['app']['viewDays'] This is the number of days to print out on each page of the scheduler. Setting this to 7 will print out a full week. $conf['app']['weekStartDay'] This is the day of the week that the schedule should start on. For example, if the week should start on Sunday, set this to 0; for Saturday, set it to 6. Valid values are 0 through 6, with 0 being equal to Sunday and 6 being equal to Saturday. $conf['app']['adminEmail'] This is the email address and login value for the administrator. phpScheduleIt allows for just one administrative account. Set this value to whatever you want to use as the administrative login and be sure to register an account with this value. You cannot log into phpScheduleIt using this address unless you register it. This email address will also be used as the 'from' address for all email contact with the users. $conf['app']['techEmail'] The email address of your technical support. This value will be used to direct technical email and all bug reports. It is highly recommended to set this value so that this technical person can help the user or report any questions to the project homepage on SourceForge and improve phpScheduleIt. $conf['app']['ccEmail'] This value should contain all email address to CC when a user clicks the 'Email Admin' link. To specify multiple email addresses, separate them with commas. $conf['app']['emailAdmin'] This setting toggles whether to send email notifications of reservation and registration activity to administrator. The only values this can be are 0 (which means that email will not be sent) and 1 (which means that email will be sent). $conf['app']['title'] This is the title to use for the application. It will be used as the default title for pages and as the 'From' field in all email contacts. $conf['app']['use_perms'] This setting toggles whether to use permissions or not. Using permissions will limit who can reserve resources. If permissions are on, only users who have been given permission to use a resource can reserve it. If permissions are turned off, anyone will be able to reserve any resource. The only values this can be are 0 (which means that permissions will not be used) and 1 (which means that permissions will be used). $conf['app']['auto_assign'] This decides if a user should be automatically given permission on all resources when they register and as new resources are added. Please understand that users will automatically be allowed to reserve all resources; the administrator will have to specifically deny permission on a per user basis. The only values this can be are 0 (which means that permissions will not be automatically given) and 1 (which means that permissions will be automatically given). $conf['app']['use_log'] This toggles the activity logging on or off. Logging writes all activity (registration, reservations, resource data) to a log file of your choice. The only values this can be are 0 (which means that logging will not be used) and 1 (which means that logging will be used). $conf['app']['logfile'] This value is the directory and file name of the log file to use. If the file does not exist, it will be created. Please specify this as /directory/filename.extension. Database SettingsAll of these settings determine the database setup. $conf['db']['dbType'] This is the database backend type. This must be a valid PEAR::DB setting. The options are: $conf['db']['dbUser'] This value is the database user who has permission to create, alter, modify and delete data from the tables phpScheduleIt uses. This value is required to access the tables. $conf['db']['dbPass'] This value is the password for the database user specified in $conf['db']['dbUser']. This value is required to access the tables. $conf['db']['dbName'] This is the name of the database to be used by phpScheduleIt for storing all system data. The user specified in $conf['db']['dbUser'] will be given permission to use all tables in this database. $conf['db']['drop_old'] This value toggles whether the automatic installation should overwrite any databases with the same name as $conf['db']['dbName']. Please be very sure about this setting. If you are in doubt, leave it set to 0. The only values this can be are 0 (which means that an existing database with the same name will not be overwritten) and 1 (which means that the aforementioned database will be overwritten). $conf['db']['pk_prefix'] This value is the prefix that will be prepended to all primary keys in this database. This is required if you will be sharing databases between multiple versions of phpScheduleIt (for example, sharing a login data but having a different resource data). This setting must be different for every instance of phpScheduleIt that is sharing the same database. 3 characters are recommended. Anything over 3 characters will be cut down to use only the first 3. User Interface SettingsAll of these settings change how the application looks and feels. $conf['ui']['announcement'] Setting this value will set announcements to be seen on My Control Panel. To add announcements, add the following line. The value between the quotation marks is the announcement text. $conf['ui']['announcement'][] = "This is an announcement"; To add more announcements, repeat the above line for each announcement. The announcements will be displayed last to first. Add '//' before or delete the line directly under $conf['ui']['announcement'] = array(); to display no announcements. $conf['ui']['logoImage'] This value is the directory and filename of the image to use as the logo. Leave this empty if you do not want to use an image. Please specify this as directory/filename.extension. This will be relative to the root directory of phpScheduleIt $conf['ui']['welcome'] This is the welcome message to show at the login screen. Leave this value blank to display no message. $conf['ui']['my_res'] This is the array that stores the color of the reservation block of all reservations that the current user owns. 'color' defines the standard color of the block, 'hover' defines the color when the mouse is over the reservation block. Please do not include the hash mark (#) when specifying the colors. To set the colors, add or alter this line. $conf['ui']['my_res'][] = array ('color' => '5E7FB1', 'hover' => '799DD3'); $conf['ui']['other_res'] To set the colors, add or alter this line. $conf['ui']['other_res'][] = array ('color' => 'D2DDEC', 'hover' => 'AFBED3'); $conf['ui']['my_past_res'] Please refer to the two variables above this for how to set it properly. $conf['ui']['other_past_res'] This is the array that stores the color of the reservation block of all reservations that the current user does not own, but have past. 'color' defines the standard color of the block, 'hover' defines the color when the mouse is over the reservation block. Please do not include the hash mark (#) when specifying the colors. Please refer to the two variables above this for how to set it properly. $conf['ui']['positions'] This is the available choices to use when a new user is registering for phpScheduleIt. If you add values to this variable, they will appear in a pull down menu. If you do not add values then the position field will be a text box instead of a pull down menu. To add positions to the pull down menu, add the following line. $conf['ui']['positions'][] = "Position Value"; To add more positions, repeat the above line for each position. They will be displayed in the order you list them. The value cannot be more than 255 characters. $conf['ui']['institutions'] This is the available choices to use when a new user is registering for phpScheduleIt. If you add values to this variable, they will appear in a pull down menu. If you do not add values then the institution field will be a text box instead of a pull down menu. To add positions to the pull down menu, add the following line. $conf['ui']['institutions'][] = "Institution Value"; To add more institutions, repeat the above line for each position. They will be displayed in the order you list them. The value cannot be more than 100 characters. Getting StartedAfter the system has been successfully installed and set up, create an account for the administrator. You can do this by navigating to the Login (index.php) page and clicking the Register link. Be sure to enter the login exactly the same as it appears in the config.php file's 'adminEmail' setting. After the Administrator account has been registered, you need to add resources. Also, as new users are added, you will need to manage their permissions to allow them to reserve a resource. Data Organization and ManagementAll data is stored in one of five tables in one database (named schedule): login, resources, reservations, training. The login table stores all user information. A self-incrementing identification number will be automatically assigned to each user. This will be used to identify users and keep the system secure. Because email addresses are used as login names, they must be distinct. Passwords are encrypted before being inserted into the database using a one-way encryption format. Due to this, users will not be able to retrieve passwords once they are stored. This is for their own (and the overall user community's) safety. Passwords can be reset from the forgot_password.php page. Columns in the login table:
The resources table stores all information about individual resources. Each resource is assigned a self-incrementing identification number. This will be used to easily identify all resources in the system and to store it's status (active or inactive). Columns in the resources table:
The reservations table is the cross of the login and resources tables. This table will store basic information about every reservation on every resource made by every user.
The permission table is again a cross of the login and resources tables. This table will store memberid's and the resources they are allowed to use. Initially, this table will contain no entries until a user has been given permission to use a particular resource.
System NavigationEntry into the phpScheduleIt system defaults to the login screen. Here a user can log in or navigate to the registration page. If a user has selected the "Keep Me Logged In" option, then they will be automatically forwarded to My Control Panel each time they return to the system (until they manually Log Out). After a successful login or registration, the user will be automatically forwarded to My Control Panel. My Control Panel is the "Home Page" for each user. They will be able to view, modify and delete their upcoming reservations. The list of reservations is sortable in ascending/descending order based on column name. Here, they will also be presented with a Quick Links table where they can navigate to the scheduler, edit their profile/password or log out of the system. Users can return to My Control Panel from anywhere in the system at any time by clicking the "My Control Panel" underneath the welcome message. The scheduler is where users book new reservations and edit past ones. Clicking on a resource's name will bring up a pop-up window where the user can reserve the resource. If the user selects a time which is already reserved by another user, the reservation will fail and they will be prompted to try again. Users CANNOT edit or delete another user's reservation. They will only be allowed to view it. Also, users cannot book or modify a reservation for a past date, an inactive resource or a resource that they have not been given permission to reserve. The administrator has the power to modify or delete any reservation in the system from both the scheduler and from the admin tool "Manage Reservations". When a user clicks the Quick Link "Edit My Profile Information/Password", they will be brought to a page resembling the Registration page with all of their information filled in (except the password). Editing the information will result in a change in the database. Blank or unchanged fields will not be altered in the database. User ManagementWarnings: When using more that one instance of phpScheduleIt are sharing a database, it is critical that all data integrity issues are addressed. For example, sharing a login table but using independent reservation/resource/training tables can result in compromised data integrity. If a user has reservations committed on more than one system and they are deleted from the global login table, their reservations will not be removed unless they are deleted from one of the secondary instances of the system. There are two main techniques that can be used to resolve this issue: 1) The shared data (in this case, the login information) must be removed from a secondary instance of the application. This secondary instance will be aware of all databases in the system and will be able to remove all data associated with the data being deleted. 2) The "leftover" data can be manually deleted from the system by an Administrator. In this example, reservations associated with deleted users can be deleted from the scheduler or from the admin tools. Notes: The initial login table will be empty. All users are required to register upon first use of phpScheduleIt. All fields in the Registration form are required. Registration will fail if the form is not completed entirely. Upon successful registration, a unique memberid will be automatically created for each user. Users can edit their personal information at any time by logging in and selecting the "Edit My Profile Information/Password" option in the Quick Links table. They will be taken to their personal information page where any of the fields can be changed. Administrative Tool : Manage Users The administrator can delete users at any time from the system by selecting the "Manage Users" option in the Quick Links table. The "Manage Users" tool will navigate to a page listing all users, sorted alphabetically (by default), showing a specific number of users at a time. The list of users can be sorted by ascending/descending order by column name. For each column, clicking on the minus sign sorts the list in descending order based on that column name, clicking on the plus sign sorts the list in ascending order based on that column name. The sorting order will be preserved throughout pages. From this table, you can email a user by clicking their email address, view all information about this user by clicking the View Info link, manage that user's training by clicking the Training link, or delete any number of users by checking their delete box. Clicking the View Info link for a user will bring up a new window listing all information about the selected user. Clicking the Permissions link will navigate to a new window where you can select which resources a user has or has not been given permission to use. Upon registration, will only have permission to use resources if auto-assign has been turned on in the config file. To grant or revoke permission for a user check or uncheck the checkbox for each resource the user is allowed to use. To delete a user, simply check the "Delete User" box for each user who the administrator wishes to remove and press the "Delete Users" button. The administrator will be prompted to verify the removal of all selected users and all of their reservations. After the successful removal of users, the Manage Users page will be refreshed showing that the changes have been made. Deleting a user will also delete ALL reservations for that user. Resource ManagementNotes: The initial resources table will be empty. Administrative Tool : Manage Resources The administrator can delete resources at any time from the system by selecting the "Manage Resources" option in the Quick Links table. The "Manage Resources" tool will navigate to a page listing all resources, sorted alphabetically (by default), showing a specific number of resources at a time. The list of resources can be sorted by ascending/descending order by column name. For each column, clicking on the minus sign sorts the list in descending order based on that column name, clicking on the plus sign sorts the list in ascending order based on that column name. The sorting order will be preserved throughout pages. To add a resource, enter the resource name, location, phone number and any notes regarding that resource into the Add Resource table at the bottom of the Manage Resources page and press the "Add Resource" button. The resource will be added into the database with a unique identification number and the Manage Resources page will be refreshed, showing the new resource. New resources will be set to "Active" by default. To modify a resource's information, click on the resource's Edit link. The information will appear in the form below. Any field that is changed will be updated in the database. Unchanged or empty fields will not be changed in the database. To delete a resource, check the Delete checkbox for each resource the administrator wishes to delete and press the "Delete Resources" button. The administrator will be prompted to verify the removal of the selected resources. Deleting a resource will also delete ALL reservations held for that resource. After the resources have been removed from the database, the Manage Resources page will be refreshed, showing the successful removal of the resources. The status column lists each resource's current status. To change a resource's status, simply click on the link in the "Status" column and the resource will either be activated or inactivated. Resource status does NOT affect previously made reservations. When adding or modifying a resource, you have the option to select the minimum and maximum reservation length. Reservations less than the minimum or greater than the maximum length specified will not be accepted. Setting these values to the same time will require that all reservations are of this length. Other Admin ToolsThe administrator's Quick Links table is different than all others. It includes the 5 basic user options plus 7 additional tools. Manage Users and Manage Resources have been described already. The rest will be described now. As a note, the admin tools can only be accessed by a user who logs in as the administrator. All other users will be locked out of any administrative page. Manage Reservations will navigate to a page listing all reservations in the database ordered by increasing date, showing a specific number of reservations per page. The list of reservations can be sorted by ascending/descending order by column name. For each column, clicking on the minus sign sorts the list in descending order based on that column name, clicking on the plus sign sorts the list in ascending order based on that column name. The sorting order will be preserved throughout pages. In this table, clicking on the user's name will open a pop-up window with all of the selected user's information. Clicking on the view, modify, delete links will open a pop-up window allowing you to view, modify or delete the selected reservation. View Scheduled Resource Usage will navigate to a search form which will allow the administrator to specify certain search criteria. The criteria is as follows: all or any specific user, all or any specific resource, all or any specific PI, starting and ending times and starting and ending dates. By default, the selected starting and ending times will be the same as what is provided in the configuration file and the selected starting and ending dates are the lowest and highest dates currently reserved. After performing the search, the results will be printed out for each user/resource combination, listed alphabetically. These results are also available in a text-only format by clicking the "Print these results to a text file" link at the top of the results page. Mass Email Users will navigate to a page where you can send a mass email to any or all of the registered users. This email can contain HTML tags, if you wish. View System Stats will bring you to a page where many statistics about almost every aspect of the system are given. Reservation statistics are also graphed out. Configuring AnnouncementsAn unlimited number of announcements can be added to the system. They are added in the config.php file. To add an announcement, simply set the value of $conf['ui']['announcement'][] to some value enclosed within quotes. Example: $conf['ui']['announcement'][] = "This is an announcement."; To add more announcements, just add more announcement variables. For example, $conf['ui']['announcement'][] = "Another Announcement"; The last announcement added will show up first, and the others will be displayed going from last added to first. If you do not want any announcements, simply delete all announcements except the first one, but place "//" in front of it. NotesAll database manipulation should be done though the Administration Tools, NOT manually. Manually editing the database can lead to data corruption and render the system unstable or useless. ChangelogVersion 0.9.3 (2004-01-24) - Auth class bug has been fixed. (See http://sourceforge.net/tracker/index.php?func=detail&aid=869070&group_id=95547&atid=611778
for more info) Version 0.9.0 stable (2003-12-28) - reservation time intervals can be managed in the config file Version 0.9.0 beta (2003-11-30) - auto-assign permissions to users upon registration option added, allowing
the user to be automatically given rights to use all resources upon registration Version 0.7.0 beta (2003-11-25) This is the first public release of phpScheduleIt. There was a good deal changed and removed from the previous version, including PI information and a lot of wording changes. Version 2.1.0 (2003-09-22) - reservation repeating is added to initial reservation popup window Version 2.0.0 (2003-09-18) - implements the PEAR::DB package, allowing for the system to connect
to most major databases Version 1.3.0 (2003-05-08) - added popup calendar navigation module Version 1.2.0 (2003-04-24) - added "Mass Email Users" tool to administrative tools Version 1.1.2 (2003-03-25) - rewrote scheduler code completely making it much more efficient by only retrieving and storing necessary reservation data and eliminating majority of database queries Version 1.1.1 (2003-03-20) - fixed bug in scheduler that would skip over successive months with less number of days than current month Resources http://phpscheduleit.sourceforge.net |