CELCAT® Timetabler 6
User Guide Part F
Utilities
User Guide Part A – Getting Started
User Guide Part B – Timetabler Administrator
User Guide Part C – Timetabler Client
User Guide Part D – Web Tools
User Guide Part E – Timetabler SAT
User Guide Part F – Utilities
User Guide Part G – Technical Reference
Utilities
Utilities
Contents Contents .......................................................................................................................... i
Foreword ........................................................................................................................ i
Terminology used in this Guide ....................................................................................... i
Typographic Conventions ................................................................................................ i
1. Timetabler AutoCal Service .................................................................................... 1
1.1 How AutoCal Service Works ............................................................................................................ 1
1.2 Requirements .................................................................................................................................... 1
1.3 Installation ........................................................................................................................................ 1
1.4 Configuring AutoCal for Use ........................................................................................................... 2
1.5 Exclusions ......................................................................................................................................... 7
1.6 Running the Service Automatically................................................................................................. 8
1.7 Running the Service Manually ....................................................................................................... 10
1.8 Changes Required in Timetabler Client ......................................................................................... 10
2. Timetabler Notification Service ............................................................................ 12
2.1 How Notification Service Works .................................................................................................... 12
2.2 Configuring the Service to Run ...................................................................................................... 12
2.3 Initialising the Service .................................................................................................................... 19
3. Timetabler Language Manager ............................................................................. 22
3.1 Requirements ................................................................................................................................. 22
3.2 Installing Language Manager ........................................................................................................ 22
3.3 Using the Language Manager ........................................................................................................ 22
4. CELCAT Timetabler Server ................................................................................... 24
4.1 Accessing the Application .............................................................................................................. 24
4.2 Disconnecting Users ...................................................................................................................... 24
4.3 Licensing the Software .................................................................................................................. 24
5. Server Manager .................................................................................................... 26
6. XML Server .......................................................................................................... 27
6.1 Assumptions and Limitations ....................................................................................................... 27
6.2 Technologies .................................................................................................................................. 27
6.3 Security........................................................................................................................................... 27
6.4 System Overview ............................................................................................................................ 28
6.5 Process Overview ........................................................................................................................... 29
6.6 XML Documents / SOAP Requests Details .................................................................................. 30
6.7 Requests and Responses ................................................................................................................ 31
6.8 Error Handling .............................................................................................................................. 48
7. Bespoke Plugins ................................................................................................... 50
7.1 Integration ..................................................................................................................................... 50
7.2 Specifying a Plugin ......................................................................................................................... 51
8. QLS Import/Export Plugin .................................................................................... 52
Utilities
8.1 Running the Plugin ........................................................................................................................ 52
8.2 Configuring the Plugin .................................................................................................................. 54
8.3 Data Mapping ................................................................................................................................ 56
8.4 Registers and Events ..................................................................................................................... 60
8.5 Filtering Lists ................................................................................................................................. 63
8.6 Synchronising ................................................................................................................................ 63
8.7 Errors ............................................................................................................................................. 64
8.8 Deleted Records ............................................................................................................................. 66
9. Timetabler COM Library ....................................................................................... 67
9.1 Getting Started ............................................................................................................................... 67
9.2 Objects ............................................................................................................................................ 69
Utilities
i
Foreword
Welcome to CELCAT Timetabler 6 Utilities – Timetabler is a specialised software application used to
develop, maintain and publish university and college timetables. This Part of the Guide discusses the
additional Timetabler utilities and is structured to give an overview of their basic concepts and use.
Please note that there are several revisions of the CELCAT Timetabler 6 applications, and the details
presented in this guide may differ slightly from those you find in your software installation.
Some functions require the use of Timetabler Client. Where this is so, this Part of the Guide will explain
how to access these features. Users needing to access such functions would benefit from a basic
understanding of how Timetabler Client and Administrator work. See the relevant Parts of the User
Guide.
For a comprehensive list, please refer to:
http://www.celcat.com/useful
Terminology used in this Guide
CELCAT Timetabler is a specialised software application and therefore has a library of unique terms.
Below is a glossary of terms that are used in this Part of the Guide. Please see the appropriate Parts of
the Guide for more detailed lists and descriptions.
Timetable: The teaching calendar created and accessed with CELCAT Timetabler. The timetable can be
for a calendar year or a specific number of weeks in a year, for example, a single teaching term.
Timetabler Administrator: A Timetabler application used to provide security and control.
Timetabler Client: The main desktop application used to create events, print reports etc.
Timetabler Web Server: An application to view and edit timetables in a web browser.
Resource: The resources for timetabling are modules, rooms, staff, groups, students, equipment and
teams.
Event: An activity associated with one or more resources, occurring at a specified time and day and
occurring in one or more weeks of the timetable. An instance of an event corresponds to a register.
Typographic Conventions
Bold Bold type is used to represent elements of the user interface that the user interacts
with, such as buttons, tabbed pages and file names, and feature mainly in task sections
of the document.
Monospaced Monospaced type like that shown is used to represent text typed at the keyboard or
displayed on screen.
Capitalisation Capitalisation is used for specific CELCAT screen items, such as the Timetable Grid
and Event window.
Utilities
1
1. Timetabler AutoCal Service
The CELCAT AutoCal service is used in conjunction with CELCAT Timetabler software to update staff
and student Microsoft Exchange calendars. The service performs periodic checks on timetable data and
communicates with your Exchange server in order to synchronize calendars
Note: AutoCal requires full administrator access to your Microsoft Exchange Server.
The service should be installed on a server computer and configured using the CELCAT AutoCal
Configuration Tool.
1.1 How AutoCal Service Works
The CELCAT AutoCal service checks for changes in the timetable data and then updates personal staff
and student calendars so that timetabled events are correctly displayed.
Here's how it works:
1. Specify the Microsoft Exchange Server on which the staff/student calendars are stored.
2. Ensure that staff and student profile names are stored correctly in Timetabler. These are the names
that AutoCal uses in order to access personal calendars on the Exchange Server.
3. Select days and times when the service can be active (ensuring that they don't coincide with periods of
intense timetabling activity).
4. Indicate whether staff and/or student calendars should be updated.
5. The AutoCal service works behind the scenes to monitor changes made to the timetable and then
updates calendars as required.
Note: AutoCal does not update appointments historically, so if you make alterations to timetabled
events that occur in the past, AutoCal ignores these changes.
1.2 Requirements
The CELCAT Timetabler AutoCal service requires that you use a Microsoft® Exchange Server. The
AutoCal service uses a Microsoft library called Collaboration Data Objects (CDO). This library will
already be present on a Microsoft® Exchange server computer, but if you wish to run AutoCal service on
another server the best way of ensuring CDO is available is to install Microsoft® Outlook and select
Collaboration Data Objects in the custom install options.
1.3 Installation
If you are installing from a CELCAT distribution CD, insert the disk and wait for the CELCAT Timetabler
launcher application to appear. If the launcher is not automatically displayed, navigate to the CD drive
and run the CTLauncher.exe file. Select the AutoCal installation item from the launcher and follow the
on-screen instructions.
The service should be installed on a server computer and configured using the CELCAT Timetabler
AutoCal Configuration Tool.
Utilities
2
1.4 Configuring AutoCal for Use
To Configure AutoCal for use you should run the AutoCal Configuration tool using the CELCAT |
Timetabler | CELCAT Timetabler AutoCal menu command. The CELCAT AutoCal Config
application is displayed. Now you can begin configuring the service.
AutoCal is configured using the tabbed pages on the configuration tool. The following sections describe
each of these pages.
1.4.1 Specifying the Server
The Server page is used to specify the name and location of the CELCAT Timetabler Server (CTServer).
Fig 1
Enter the Machine name of the computer on which your CELCAT Timetabler Server application is
running. If it's running on the same machine as the AutoCal service, you can leave the Machine name
field blank. Click the Test button to ensure that the Timetabler Server exists and can be accessed.
1.4.2 Selecting Timetable
The Timetable page is used to specify the timetable database to use.
Utilities
3
Fig 2
The service operates on a single CELCAT timetable. Click the Change button to display the Select
Timetable form, and select a timetable to use.
Fig 3
The Name is the name of the CELCAT timetable. The Server name is the name of the SQL Database
server on which the timetable is stored, and the Database name is the name of the timetable database.
1.4.3 Configuring MS Exchange Options
Exchange calendars are stored on a Microsoft Exchange Server. You need to specify the name of the
server and indicate whether staff and/or student calendars are to be updated.
Utilities
4
Fig 4
Click the Test button to test that the specified Exchange Server exists. The Mailbox form invites you to
input a Mailbox name.
Fig 5
AutoCal advises you of the test results as shown below:
Fig 6
Note: The „Test‟ function described above, simply checks for the existence of the Microsoft Exchange
Server that you have specified. Because AutoCal runs as a service (and not necessarily under the context
of a user account), you must ensure that the account under which it runs has permissions to access your
Microsoft Exchange Server. Use Control Panel | Administrative Tools | Services to determine the
Utilities
5
name of the account used to „Log On‟ the CTAutoCal service. By default this is the SYSTEM account,
which is usually sufficient to access a locally installed Microsoft Exchange server. However, if it is remote
then you should change the account to provide appropriate access rights.
1.4.4 Specifying how Events Appear in Outlook Calendars
The Events page allows you to specify how CELCAT Timetabler events appear in Microsoft Exchange
calendars.
Fig 7
Subject Line
These options allow you to specify which part of the event is placed on the appointment subject line. If
you want fixed text to appear, such as "Timetable Event", check the User-defined text radio button
and enter your text in the User-defined text field. The Set reminder checkbox when ticked
corresponds with the reminder option in Outlook Calendar.
Appointment Body
The main text of calendar appointments can contain selected resource information for the timetabled
event; including Module, Group, Room and the Staff member. Use the checkboxes to specify which
elements should be included.
Event attributes allows you to include the Event Category details and any notes associated with the
event.
Log File
Enter the path of a log file that can be used to store a record of the service activity. The default location is
in the same folder as the service executable.
Note: You must ensure that the path is accessible when the service is running unattended and without
anyone logged into the computer (mapped drives - networked disk drives that are associated with a drive
letter, e.g. 'N:' are not normally available in these circumstances).
Note 2: The log file is discarded if it grows over 1Mb in size (actually it is renamed with a ".bak"
extension and a new log file created).
Utilities
6
1.4.5 Configuring the Destination for Error Alerts
If the AutoCal service encounters an error it can send an email alert to a specified destination. The
Alerts page is used to configure the email server and email address to be used.
Fig 8
Enter the name of your SMTP server, e.g. mail.wincote.ac.uk. This is the only compulsory field.
Note: There is no option to change the standard SMTP port (25)
If your SMTP server requires user authentication, provide an appropriate User name and Password
in the fields provided.
The „From‟ name and „From‟ address fields allow you to enter the name of the email sender
(typically "CELCAT Timetabler"). These fields are optional and can be used to identify the source of
notification messages.
The Alert email address field is for you to enter the address that the alert email should be sent to. If
you want to send alerts to more than one address you should set up an email group and specify its name
here.
Test - Click the Test button to test connectivity with the specified SMTP Server.
1.4.6 Setting the Times When the AutoCal Service Runs
The Times page is used to indicate when you want to prevent the service from being active (i.e.
accessing the timetable data and updating calendars). This is usually done to prevent the service from
interfering with database backups, routine maintenance etc.
Utilities
7
Fig 9
The grid runs from midnight to midnight and has a granularity of 30 minutes. Click in the grid to toggle
between Active and Inactive states.
In the above example the service is inactive during normal office hours, Monday to Friday because it
might slow the system down for other users. Additionally, the service is inactive on Saturday.
Note: When specifying times, you are not restricting the running of the service (in normal operation it
runs continuously); rather you are preventing the service from operating on the timetable database at
certain times.
1.5 Exclusions
The Exclusions page is used to specify items that should not be included in the AutoCal operation.
Event Categories
Click the Event Categories button to display the Event category browse list. Specify the categories of
events that are to be excluded when AutoCal runs. This is useful if
you do not want to create calendar appointments for all of the CELCAT Timetabler events.
Tick the “No event categories” checkbox to exclude those events having no category.
Staff
Select any members of staff who do not want their calendars updating. Remember that staff must also
have a valid Exchange profile in their staff record window in order to update their calendars.
Note that the Staff button is disabled if the Staff checkbox on the Exchange page is unticked.
Students
Select any students who do not want their calendars updating. If you do not want any students included,
the best way is to untick the Students checkbox in the Exchange page.
Remember that students must also have a valid Exchange profile in their staff record window in order to
update their calendars.
Note that the Students button is disabled if the Students checkbox on the Exchange page is unticked.
Utilities
8
Fig 10
1.6 Running the Service Automatically
The AutoCal Configuration Tool can interact with the service using controls on the Service page. From
the Service page you may install the service to run automatically as well as Start and Stop the service.
The Current status indicates the current status of the service as follows:
Not installed - The service has yet to be installed.
Stopped - The service is installed but is not running.
Running - The service is installed and running.
Click the Start button to display the Start service form, which allows you to start the service in
production mode or test mode.
Production - In normal operation you should run the service in Production mode.
Test - Run in test mode if you want to ensure that the service can communicate correctly with
the CTServer and database. Once running in Test mode you should see some activity displayed
although no calendars are updated. When you are happy that the service is working correctly
you can stop it and then restart using the Production running mode.
Note - Even though the service is running it may not always be active - AutoCal service is constrained to
operating within user-specified times and may also choose to deactivate itself when many people are
using the timetable data.
Utilities
9
Fig 11
To stop the service, click the Stop button. Occasionally there may be a short delay between pressing the
Stop button and the current status reporting "Stopped".
Click the Install button to display the Install form which allows the service to be registered with
Window's Service Control Manager. You will need to enter the path to the service executable (you do not
need to specify the executable file name; just the folder). Use the ellipsis button to the right of the text
control to select the folder using a window.
Fig 12
Starting mode
Select the service starting mode. Use manual mode if you want to manually control when the service
starts and stops. Use automatic (the default setting) to ensure that the service runs whenever the
computer is switched on.
The Uninstall button uninstalls the service. This button is greyed out if the service is not installed.
The Current activity field displays the names of staff and students that are being processed by the
service.
Utilities
10
Note: Even though the service is running it may not always be active - AutoCal service is constrained to
operating within user-specified times and may also choose to deactivate itself when many people are
using the timetable data.
1.7 Running the Service Manually
The Interactive page allows you to run AutoCal functions directly from the AutoCal Config application
(not via the service). The advantage of this is that it allows you to control and monitor the activity. The
interactive facility is generally only used to test AutoCal functions, but you can run the process in a
production environment if you wish (the disadvantage is that your computer must be logged on and the
AutoCal Config application running).
Fig 13
When running interactively, AutoCal uses all of the service settings specified in the other AutoCal Config
pages, such as timetable name, exchange server details, etc.
Click the Start button to start AutoCal processing. Progress is indicated in the Activity box.
When AutoCal is working, the Start button caption changes to “Stop”.
Note: When you click Stop, it may take a few moments before the application finally stops processing.
In normal operation, AutoCal only updates Staff/Student calendars when it detects that changes have
been made to their timetables since the previous AutoCal run. Tick the Force updates checkbox to
have AutoCal ignore this requirement and update calendars regardless.
In normal operation, AutoCal checks for changes, etc every ten minutes. Tick the Accelerate checkbox
to remove the ten-minute delay.
Note - The Force updates and Accelerate options should only be used for test purposes because of
the extra demands they place on the server.
1.8 Changes Required in Timetabler Client
For AutoCal to update staff or student Outlook calendars it is necessary that Timetabler contain their
Outlook profile names.
Utilities
11
The Profile is recorded in the Timetabler Client application, in the student or staff record window as
shown below (in the Contact page).
The Profile field is used to store the staff/student Exchange profile name.
Fig 14
AutoCal needs this information to know which Calendar to populate with timetabled events. If the
profile is not present then Outlook will ignore the record.
Once AutoCal is configured correctly and calendars are synchronised the appointments appear in the
calendar in the usual way.
Fig 15
Utilities
12
2. Timetabler Notification Service
The Timetabler 6 Notification service is used in conjunction with CELCAT Timetabler software to notify
staff and students of changes to their timetables. The service performs periodic checks on timetable data
to determine when an important change has been made and then notifies relevant staff and/or students
using email or SMS (Short Message Service or text messaging).
2.1 How Notification Service Works
The Notification service checks for critical changes in the timetable data and then informs the relevant
staff and/or students that changes have been made. Here's how it works:
1. You specify days and times when the service can be active (ensuring that they don't coincide
with periods of intense timetabling activity).
2. You indicate whether staff and/or students should be notified of changes that affect them.
3. You choose whether interested parties are notified using email, text messaging or both.
4. The Notification service works behind the scenes to monitor changes made to the timetable and
then sends appropriate notification messages.
5. The service uses a special heuristic to ensure that notifications are sent in a timely way without
being intrusive to recipients, and without compromising system performance.
2.2 Configuring the Service to Run
The Timetabler 6 Notification Configuration Tool is used to configure the operation of the Notification
service.
The service should be installed on a server computer and configured using the CELCAT Timetabler
Notification Configuration Tool. Once installed, run the configuration tool using the CELCAT |
Timetabler | CELCAT Timetabler Notification menu command.
Note: Because CELCAT Timetabler Notification service runs as a service (and not necessarily under the
context of a user account), you must ensure that the account under which it runs has permissions to
access your Timetabler Server. This is accomplished using Control Panel | Administrative Tools |
Services to determine the name of the account used to „Log On‟ the Notification service. By default this
is the SYSTEM account, which is usually sufficient to access a locally installed Timetabler Server.
However, if the server is remote then you should change the account to provide appropriate access
rights.
Additionally if you wish to notify recipients of changes by email it will be necessary to configure the
account used to access the specified Microsoft Exchange server. Because CELCAT Timetabler
Notification service runs as a service (and not necessarily under the context of a user account), you must
ensure that the account under which it runs has permissions to access your Microsoft Exchange server
As with the Timetabler Server, by default this is the SYSTEM account, if the server is remote then you
should change the account to provide appropriate access rights.
Utilities
13
The configuration tool consists of the following tabbed pages: Server, Timetable, Email,
Notification, Times, Exclusions and Service.
2.2.1 Server Page
Fig 16
The Server page is used to specify the name and location of the CELCAT Timetabler Server (CTServer).
You must enter the Name of the CELCAT Timetabler Server application, usually:
CTTServer.CELCAT_TT_Server
Do not modify this unless instructed to do so by CELCAT Technical Support.
Machine name - Enter the name of the computer on which the CTServer application is running. If it's
running on the same machine as the Notification service, you can leave the Machine name field blank.
Click the Test button to ensure that the service can communicate with the Timetabler Server.
Note: The „Test‟ function described above simply checks for the existence of the Timetabler Server.
Because CELCAT Timetabler Notification service runs as a service (and not necessarily under the
context of a user account), you must ensure that the account under which it runs has permissions to
access your Timetabler Server. Use Control Panel | Administrative Tools | Services.
2.2.2 Specifying the Timetable to be Used
The Notification service operates on a single CELCAT timetable.
Utilities
14
Fig 16
To specify the timetable to use, select the Timetable page and click the Change button to display the
Select Timetable form.
Fig 18
Select the timetable to use. The chosen timetable Name, Server name and Database name appear
in the Timetable page.
2.2.3 Sending Email Notifications
Notifications may be sent using Email and/or SMS. To use email notification you must provide details of
your email server in the Email page.
Utilities
15
Fig 19
SMTP Server name - Enter the name of your SMTP (Simple Mail Transfer Protocol) server, e.g.
mail.wincote.ac.uk
Note: The SMTP Server name is the only compulsory field. There is no option to change the standard
SMTP port (25).
User name & Password - If you need to provide a login account for your SMTP server, please specify
the User name and Password.
From name and address - These fields are optional and can be used to identify the source of
notification messages.
Note: The Test button on the Email page endeavours to connect to the SMTP server that you specify.
You must ensure that the account under which it runs has permissions to access the server. Use Control
Panel | Administrative Tools | Services to determine the name of the account used. By default this
is the SYSTEM account. If the server is remote then you may need to change the account to provide
appropriate access rights.
2.2.4 Email and/or SMS Notifications
The CELCAT Timetabler 6 Notification service allows you to stipulate whether staff and students are to
be notified by email, SMS (text messaging) or both. The Notification service only sends email
notification if the staff and student records have valid email addresses (these are entered using the
Timetabler Client software). Similarly, the staff and student 'Mobile' phone fields must be specified in
Timetabler Client in order to send text messages. The service will ignore invalid or missing fields.
Recipients‟ mobile phone numbers and email addresses are recorded in the Contact pages of staff and
student record windows.
The Notification page allows you to specify the following options: Staff & Students notification, Email
and/or SMS notification message, an alert email address and log file location.
Utilities
16
Fig 20
Student and Staff Notification
Tick the appropriate checkboxes to indicate whether staff and/or students are to be sent notifications.
Note: For notifications to be sent to students they must be directly allocated to events.
Email and SMS Notification Message
Enter the message that is to be included in the body of the notification email/SMS. By default,
Notification service indicates the weeks in which the timetable has changed. The message you enter here
is appended to the default text.
Note 1: The caption of the email message reads Timetable Changed and this cannot be changed. The
messages sent are generic and cannot be tailored to each individual recipient. For SMS notification
message you must type a brief text message, such as "Your timetable has changed" otherwise recipients
will receive blank messages.
Note 2: If you wish to send notification messages by using SMS you will need to set up an account with
one of the supported internet-based SMS service providers. You must specify the account settings for
SMS in Timetabler Administrator as shown below.
Utilities
17
Fig 21
SMS settings are configured on the Settings page, Communications sub-page of Timetabler
Administrator (see User Guide Part B – Timetabler Administrator).
Alert Email
Because CELCAT Timetabler Notification service runs unattended on a server computer, it is a good idea
to configure the software to send you alerts by email if an error occurs (e.g. if the service can‟t connect to
the Timetabler Server). You can specify the alert email address in the Alert email field on the
Notification page. Enter the email address that is to receive alerts when the service generates an error
condition.
Log File
Enter the path of a log file in the Log file field that can be used to record the service activity.
Note: Ensure that the path is accessible when the service is running unattended and without anyone
logged into the computer. Mapped drives (networked disk drives that are associated with a drive letter,
e.g. 'N:') are not normally available in these circumstances. The default location is the same folder as the
service executable.
2.2.5 Setting Times for the Service to Run
The Times page is used to indicate when you want to deactivate the service (i.e. prevent it from
accessing the timetable data and sending notification messages). This is usually done to prevent the
service from interfering with database backups, routine maintenance etc.
The grid runs from midnight to midnight and has a granularity of 30 minutes. Click in the grid to toggle
between Active and Inactive states.
Utilities
18
In the following example the service is deactivated during normal office hours, Monday to Friday
because it might slow the system down for other users. Additionally, it is blocked at times when it would
be undesirable to send text message alerts and to allow nightly database backups to be performed.
Fig 22
Note: When specifying times, you are not restricting the running of the service (in normal operation it
runs continuously); rather you are preventing the service from operating on the timetable database at
certain times.
2.2.5 Exclusions
The Exclusions page is used to specify items that should not be included in the Notification Service
operation.
Event Categories
Click the Event Categories button to display the Event category browse list. Specify the categories of
events that are to be excluded when Notification Service runs.
Tick the “No event categories” checkbox to exclude those events having no category.
Staff
Select any members of staff who do not want notifying. Remember that staff must also have a valid email
addresses and/or sms numbers in their staff record window in order to be notified.
Students
Select any students who do not want notifying. If you do not want any students included, the best way is
to untick the Student SMS and Student email checkboxes in the Notification page.
Remember that students must also have a valid Exchange profile in their staff record window in order to
update their calendars.
Utilities
19
Fig 23
2.3 Initialising the Service
The Notification Configuration Tool interacts with the service using controls on the Service page. Use
this page to initialise the service to run on your server automatically.
Fig 24
The following fields are available:
Current Status – This indicates the current status of the service as follows:
Not installed – The service has yet to be installed.
Stopped - The service is installed but is not running.
Running - The service is installed and running.
Click the Start button to displays the Start form. The Start form allows you to state the mode of
operation.
Utilities
20
Fig 25
The modes of operation are:
Production mode – In normal operation you should run the service in Production mode.
Test mode – Run in test mode if you want to ensure that the service can communicate
correctly with the CTServer and database. Once running in Test mode you should see some
activity displayed although no notifications are sent. When you are happy that the service is
working correctly you can stop it and then restart using the Production running mode.
Note: Even though the service is running it may not always be active - Notification service is
constrained to operating within user-specified times and may also choose to deactivate itself when many
people are using the timetable data.
Click the Stop button to stop the service. Occasionally there may be a short delay between pressing the
Stop button and the current status reporting "Stopped".
Click the Install button to display the Install form where you can specify the path to the service
executable and the starting mode.
Path – Enter the path to the service executable (you do not need to specify the executable file
name; just the folder). Use the ellipsis button to the right of the text control to select the folder
using a window.
Starting mode – Use this to select the service starting mode. Use manual mode if you want to
manually control when the service starts and stops. Use automatic (the default setting) to
ensure that the service runs whenever the computer is switched on.
Utilities
21
Fig 26
Click the Uninstall button to uninstall the service.
Current activity – This field displays the names of staff and students that are being processed by the
service.
Note: Even though the service is running it may not always be active - Notification service is
constrained to operating within user-specified times and may also choose to deactivate itself when many
people are using the timetable data.
Utilities
22
3. Timetabler Language Manager
The CELCAT Timetabler 6 Language Manager is a utility that allows users licensed with multiple
language versions of Timetabler to alternate between language translations. Please contact us for a full
list of Timetabler language editions.
3.1 Requirements
To use Language Manager you need additional language editions of Timetabler 6 installed on your
machine. If you require any of the additional language translation editions, please advise CELCAT at the
time of ordering your software.
3.2 Installing Language Manager
Language Manager is installed using your CELCAT Timetabler 6 installation CD (CD
drive:\CTLauncher.exe). The Timetabler Launcher contains an option to install the Language Manager.
Click on this option and then follow the onscreen prompts to install the activity.
Fig 27
The Language Manager should be installed on the same machine as your Timetabler language editions.
3.3 Using the Language Manager
To select an alternative language edition all Timetabler applications need to be closed.
Open the Language Manager utility. Language Manager is normally accessed using the CELCAT |
Timetabler | CELCAT Language Manager command. The Language Manager is displayed.
Utilities
23
Fig 28
To select the desired language use the drop-down menu. Highlight your chosen language from the list
and click the Save button. An indication of the language‟s „completeness‟ is displayed at the bottom of
the window – this is simply a measure of how complete a particular language edition is.
Utilities
24
4. CELCAT Timetabler Server
CELCAT Timetabler Server (CTServer) is the middleware application that communicates directly with
the Timetabler databases. All Timetabler client applications communicate with the timetable database
via the Timetabler Server (see User Guide Part G – Technical Reference for more information).
4.1 Accessing the Application
Timetabler Server normally runs automatically (it doesn‟t need to be run explicitly by a user), and it runs
in the background without displaying a graphical user interface. This means that in normal operation
you install the Timetabler Server and forget about it. However, you can force it to display a window, by
launching it using the CELCAT | Timetabler | CELCAT Timetabler Server command.
Fig 29
The window simply lists all connected users and provides command buttons to Disconnect users and
Licence the Timetabler software.
4.2 Disconnecting Users
To disconnect a user highlight the user in the list and select the Disconnect button.
Note: This is not the recommended method for disconnecting users. Normally users should be removed
from the system using Timetabler Administrator.
4.3 Licensing the Software
Click the Licence button to display the Licence window and enter the licence details as they appear in
the installation materials supplied with your Timetabler CD. Again, this function is normally performed
using Timetabler Administrator software.
Utilities
25
Fig 30
Utilities
26
5. Server Manager
The CELCAT Timetabler Server Manager is a tool that allows you to check the status of the Timetabler
Server application.
The Timetabler Server Manager is available from the CELCAT | Timetabler | CELCAT Timetabler
Server Manager command.
Fig 31
The Server Manager application displays the status of the server, the number of active connections, the
version number of the current installation and the location of the Timetabler Server installation.
Utilities
27
6. XML Server
The XML Server is a web-enabled interface to the Timetabler data that allows 3rd-party software
developers to construct import/export/synchronize routines with little or no knowledge of the inner
workings of Timetabler, and without extensive assistance from CELCAT.
6.1 Assumptions and Limitations
XML Server works as a data provider layer. It doesn‟t offer any user interface or visual classes to use by
3rd party software developers. We assume all GUI/Web pages development work takes place at a 3rd
party software company.
The Interface allows for many simultaneous connections through selected CELCAT Timetabler Servers,
possibly from more than one application/web service.
The Interface is method oriented. It publishes functions that can be executed remotely on the server.
They send back plain text or XML as a response.
6.2 Technologies
The Interface is designed to work both as an interactive Windows application and system service. It uses
HTTP/HTTPS transmission protocol to exchange data over the internet or intranet (HTTP/HTTPS Post
method is required to send any request to the Interface).
The XML Interface is implemented as a SOAP Web Service (Simple Object Access Protocol) and can be
published and invoked over the Internet. Web Services are not designed for direct human interaction.
Rather, they are accessed programmatically by client applications.
All SOAP requests and responses use XML to encode remote procedure calls and responses. The SOAP
Service publishes information on what interfaces and functions are available and how to call them using
a WSDL (Web Service Definition Language) document, which is available under the SOAP service URL.
A sample file will be attached to this document (however – it will not contain valid URL addresses).
On the client side, a wizard or command-line utility can import a published WSDL document, providing
you with the interface definitions and connection information needed. In that case, a SOAP client
method call should be performed to send a remote procedure call. Client-side WSDL import utilities are
usually integrated into development environments. CELCAT does not provide any WSDL import utility.
6.3 Security
The Interface takes advantage of the currently defined access rights mechanism. Only Timetabler users
with an Administrator role available to them are allowed to use the XML Server interface.
Administrative users have no restrictions to Timetabler data. However, tables that contain
administrative data (not data about resources, timetables, etc) are not made available via the interface.
We assume, that any user using external systems are verified by the external application to have access
to a particular timetable. Thus we don‟t require the user to be verified again before granting access to
Timetabler data. Additionally, we provide a user-verification mechanism in order to allow for checking
Utilities
28
whether a user a Timetabler account and assigned Timetabler role – however this is not a mandatory
function.
In the current version of the Interface we don‟t allow for any modification of data stored in Timetabler
database. See the COM Library if you require the ability to write to a Timetabler database.
Support is provided for both standard (HTTP) and secure (HTTPS) transmission protocol.
The XML Server works independently of any other CELCAT web services. However, it is possible to use
the same SSL certificate as used for the CELCAT Timetabler Web Server.
Client machines should allow for sending cookie files in order to maintain session parameters. Similarly,
client applications should be designed in a way that allows for cookie transmission (in particular, client
SOAP or HTTP components should be able to receive and transmit cookies).
In order to prevent access to particular databases there is a flag in Timetabler Administrator labelled
„Enable XML Interface‟. Users will only be able to log in to databases that have this option enabled.
We recommend using HTTPS when sending the Login request, as the timetable‟s administrator
credentials are being transmitted.
6.4 System Overview
Fig 32
The Web Application is any system that is developed to exchange data with Timetabler databases using
the XML Server.
XML Server Config is used to configure the CELCAT Timetabler Server machine and application, HTTP
ports and SSL Certificate used. It also can install/uninstall the XML Server service on the local machine
as a Windows system service.
The XML Server is an interactive application/windows service that interprets requests, and fetches
requested data using CELCAT Timetabler Server. It also publishes WSDL Schema to any SOAP client
application or WSDL importing tool.
The CELCAT Timetabler Server is a DCOM Server used by all CELCAT Client applications It provides
user authentication, database management, and access to timetable data.
SQL Server is the physical location of the SQL Databases containing CELCAT Timetables.
Utilities
29
6.5 Process Overview
The following diagram represents a sample process overview. It is based on an existing system,
implemented by one of our customers.
Fig 33
6.5.1 Process Description
The „My Timetable‟ web application fetches available timetables (the timetable databases registered on a
CELCAT Timetabler Server are accessible via the XML Server). The system administrator is able to
define the default Timetabler database that each student logs into. The „My Timetable‟ application
performs user verification, and allows successfully verified users (students) to issue timetable requests.
These consist of three consecutive HTTP requests. A successful response contains the requested dataset.
All web page creation routines are performed by the „My Timetable‟ system, along with display
properties management.
The XML Server interprets HTTP and SOAP requests and uses a CELCAT Timetabler Server to get
requested datasets and close initiated sessions. It also builds response data packages and in the case of
any errors, passes error messages into a response package.
Requests/Responses Description
ListTimetables request – doesn‟t require any additional parameters.
ListTimetables response – contains a list of Timetabler databases registered on the default
Timetabler Server.
LogIn request – requires 3 parameters: Database Name, Timetabler User Name (that has
administrator role available) and Password.
LogIn response – contains message „OK‟.
Utilities
30
One of the following: GetEvents, GetResources, ResUniqueNameToID request. Usually there
will be many GetEvents, GetResources, ResUniqueNameToID requests per session as each call
returns a set of events for one particular week.
One of the following: GetEvents, GetResources, ResUniqueNameToID XML string that
encapsulates returned dataset.
LogOut request – no parameters needed.
LogOut response - contains message „OK‟.
Error response. Might be sent in response to any request should any error occurred. Contains
information about request name, error number and error message, all encoded into an XML
string.
6.6 XML Documents / SOAP Requests Details
6.6.1 Standards (xml, characters, coding, data types, date formatting)
All requests/responses can be issued/received in two ways:
SOAP client object method call (explained later).
HTTP/HTTPS Post method with properly formatted XML request document as request
parameter of POST method.
Full character set (UTF-8) can be used in alphanumeric and text fields. However, if an XML request is
formed without using SOAP Client component, the following characters should not be used: <, >, &. If
any parameter (data field within the request) contains those characters, they should be changed into <
> & respectively. In the case of responses, a similar rule is applicable: all occurrences of <, >,
& should be translated into <, >, & respectively.
The following data types are used within the interface:
Bool
WideString
Long
DateTime – These are transmitted as WideStrings and specified in ISO-8601 format (yyyy-mm-
ddThh:mm:ss.sss). We assume that a zero date = 1899-12-30T00:00:00.000. Any date prior to this
value can cause an error.
ResourceTypes – An enumeration list with the following values: Module = 601, Group = 602, Staff =
603, Room = 604, Student = 605, Equipment = 606, Team = 607.
DataPacket – This is an XML string that encapsulates a requested record set. Its structure depends on
the requested data. A sample DataPacket of XML is shown later.
6.6.2 Submitting Requests
If the SOAP interface is not used, all requests should be posted via HTTP/HTTPS POST method with a
correctly formatted XML request.
Utilities
31
6.7 Requests and Responses
6.7.1 GetDefaultCTServer
Returns the name of CELCAT Timetabler Server, as configured by XML Service Config. It consists of the
machine name and CELCAT Timetabler Server name, separated by colon. If the machine name is not
provided then we assume it refers to the local machine and its name is not returned.
Parameters: none
Return Type: WideString
SOAP method:
WideString Result = Test->GetDefaultCTServer();
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetDefaultCTServer xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetDefaultCTServerResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">MYMACHINE:CTTServer.CELCAT_TT_Server</return>
</NS1:GetDefaultCTServerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.2 ListTimetables
Connects to the default CELCAT Timetabler Server (specified by the XML Server configuration). If the
default has not been configured or is empty, it connects to the local server. Returns a DataPacket
describing all Timetabler databases registered on the server. If there are no timetables available on the
server then return tag contains an empty string.
Parameters: none
Utilities
32
Return Type: DataPacket – each record contains three WideString fields:
Column Data type Size
sql_server_name WideString 64
database_name WideString 100
timetable_name WideString 30
SOAP method:
WideString Result = Test->ListTimetables();
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ListTimetables xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ListTimetablesResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:ListTimetablesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.3 LogIn
Establishes a new session (connection to CELCAT Timetabler Server) for the XML Server. Before
sending that request you need to ensure that the timetable database is accessible from the XML Server
(its SQL Server machine is accessible on the network and the database has the correct version number
and correct setting in CELCAT Timetabler Administrator). The CELCAT Timetabler server machine
name and server name are selected from the XML Server configuration stored in the local machine
registry. However, the SQL Server name and timetable database name (not the same as the timetable
name presented in Timetabler Administrator or Timetabler Client) should be provided as parameters. If
the SQL Server machine name is not provided, the interface will try to log in to the local server. We allow
only administrator roles to be used. Users with no administrator role available to them are rejected.
After a successful connection to the Timetabler Server, further requests for data may be sent.
Utilities
33
Parameters:
Data Type Name Comment
WideString SQLServer SQL Server machine name
WideString Database Timetabler database name
WideString User Timetabler Administrator user
WideString Password
Return Type: WideString. Expected result is the word “OK”.
SOAP method:
WideString SQLServer = "", Database = "", User = "", Password = "";
WideString Result = Test->LogIn(SQLServer, Database, User, Password);
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><NS1:LogIn
xmlns:NS1="urn:CELCAT">
<SQLServer xsi:type="xsd:string"></SQLServer>
<Database xsi:type="xsd:string"></Database>
<User xsi:type="xsd:string"></User>
<Password xsi:type="xsd:string"></Password>
</NS1:LogIn>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:LogInResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">OK</return>
</NS1:LogInResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.4 LogOut
Logs out from the Timetabler database and closes the session. Any further requests will need to initiate a
new session using the LogIn() call and will require all authorisation data.
Parameters: none
Return Type: WideString. Expected result is the word “OK”.
Utilities
34
SOAP method:
WideString Result = Test->LogOut();
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:LogOut xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:LogOutResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">OK</return>
</NS1:LogOutResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.5 GetUserRoles
Lists roles available to the selected user. User must be logged in before calling the GetUserRoles request.
Returns a data packet containing the list of roles. If there are no roles available for the user, or the
specified username does not exist, the response contains an empty string in the return tag.
Parameters:
Data Type Name Comment
WideString UserName CELCAT user name
Return Type: DataPacket. Data returned in the data package – below:
Column Data type Size
role_name Varchar 64
role_id Long 4
is_admin Bool 1
is_default Bool 1
SOAP method:
WideString UserName = ""
Utilities
35
WideString Result = Test->GetUserRoles(UserName);
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetUserRoles xmlns:NS1="urn:CELCAT">
<UserName xsi:type="xsd:string"></UserName>
</NS1:GetUserRoles>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetUserRolesResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:GetUserRolesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.6 ValidateUser
Checks the validity of the specified user, role and password. The user must be logged in before calling the
ValidateUser request. Parameters are CELCAT Timetabler username, password and role name for a
specific user (not the administrator account used to log in, but i.e. a student, that has her own user
account defined in the system). If an empty role name is provided, the user is validated against his
default role (basically only username and password are checked). Returns “OK” if the user is successfully
validated, otherwise “Fail”. It‟s up to the 3rd party system to call the LogOut request if the user is not
validated. This mechanism is not mandatory.
Parameters:
Data Type Name Comment
WideString User Student‟s user name
WideString Password
WideString Role Student‟s role name
Return Type: WideString. Expected result is the word “OK” or “Fail”.
SOAP method:
WideString User = “”, Password = “”, Role = “”;
WideString Result = Test->ValidateUser(User, Password, Role);
Utilities
36
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ValidateUser xmlns:NS1="urn:CELCAT">
<User xsi:type="xsd:string"></User>
<Password xsi:type="xsd:string"></Password>
<Role xsi:type="xsd:string"></Role>
</NS1:ValidateUser>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ValidateUserResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">OK</return>
</NS1:ValidateUserResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.7 GetEvents
This request returns a list of events for one resource (e.g. a student) in either one week or in all weeks of
the timetable if no date is specified. Output contains an XML string (datapacket) with all the requested
data. The user has to be logged in before sending this request. If there are no events for the particular
resource , or if the resource ID could not be found, the return tag contains an empty string.
Utilities
37
Parameters:
Data Type Name Comment
ResourceTypes ResourceTypes Enumeration value for student
(Student = 605)
Long ResourceID Student‟s id in Timetabler
database (CT_STUDENT)
WideString WeekDate Only date part is significant
(yyyy-mm-dd will be enough).
Week number will be selected
basing on the provided date.
Empty string passed as a
parameter will cause this field to
be ignored (all events will be
returned regardless of the
week).
Bool IncludeParentEvents True/false
Bool IncludeGlobalEvents True/false
Bool ReturnAllFields True/false
Return Type: DataPacket. Data returned in the data package depends on the ReturnAllFields option.
If it‟s false then a reduced set of fields will be returned (but it contains all data required to construct a
timetable). If ReturnAllFields is true then all fields from the event table will be returned. All records are
ordered by date and start time.
Simplified data packet contains the following fields:
Column Data type Size
event_id Int 4
Date* DateTime 8
start_time** DateTime 8
end_time DateTime 8
event_category_id Int 4
event_category_name Varchar 64
week_number Int 4
resource_id Int 4
resource_name Varchar 64
resource_unique_name Varchar 64
Weeks Varchar 54
* Contains exact date of the event. The Time part of the DateTime datatype should = 00:00.
Utilities
38
** Start_time and End_time contain beginning and end time of the event.
Full data packet contains the following fields:
Column Data type Size
event_id Int 4
Date DateTime 8
start_time DateTime 8
end_time DateTime 8
event_category_id Int 4
event_category_name Varchar 64
week_number Int 4
resource_id Int 4
resource_name Varchar 64
resource_unique_name Varchar 64
Weeks Varchar 54
break_mins Int 4
span_id Int 4
tag1 Varchar 10
tag2 Varchar 10
capacity_req Int 4
department_id Int 4
global_event Char 1
Protected Char 1
suspended Char 1
Grouping_id Int 4
Registers_req Char 1
Lock Int 4
Notes Varchar 16
date_change DateTime 8
original_id Varchar 32
SOAP method:
ResourceTypes ResourceType = Student;
WideString WeekDate = WideString(“2006-06-10T00:00:00”);
int ResourceID = 0;
bool IncludeParentEvents = false, IncludeGlobalEvents = false,
ReturnAllFields = false;
AnsiString output = Test->GetEvents(ResourceType, ResourceID, WeekDate,
IncludeParentEvents, IncludeGlobalEvents, ReturnAllFields);
delete WeekDate;
XML Request:
<?xml version="1.0"?>
Utilities
39
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetEvents xmlns:NS1="urn:CELCAT">
<ResourceType xmlns:NS2="urn:MainForm1"
xsi:type="NS2:ResourceTypes">Student</ResourceType>
<ResourceID xsi:type="xsd:int">0</ResourceID>
<WeekDate xsi:type="xsd:string">2006-06-10T00:00:00</WeekDate>
<IncludeParentEvents xsi:type="xsd:boolean">false</IncludeParentEvents>
<IncludeGlobalEvents xsi:type="xsd:boolean">false</IncludeGlobalEvents>
<ReturnAllFields xsi:type="xsd:boolean">false</ReturnAllFields>
</NS1:GetEvents>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetEventsResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:GetEventsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.8 GetResources
This request returns a list of assignments of other resources (rooms, staff members, modules) allocated
to events. It returns assignments using the same „logic‟ as the GetEvents request, so for the same
parameters will receive assignments for all events that the GetEvents request would return. Output
contains an XML string (datapacket) containing all the requested data. The user has to be logged in
before sending this request. If there are no events for a particular resource (e.g. student), or if the
resource‟s ID could not be found, the return tag will contain an empty string.
Utilities
40
Parameters:
Data Type Name Comment
ResourceTypes ResourceTypes Enumeration value for student
(Student = 605)
Long ResourceID Student‟s id in Timetabler
database (CT_STUDENT)
WideString WeekDate Only date part is significant
(yyyy-mm-dd will be enough).
Week number will be selected
basing on the provided date.
Empty string passed as a
parameter will cause this field to
be ignored (all events will be
returned regardless of the
week).
Bool IncludeParentEvents True/false
Bool ReturnAllFields True/false
Bool IncludeModules True/false
Bool IncludeGroups True/false
Bool IncludeStaff True/false
Bool IncludeRooms True/false
Bool IncludeStudents True/false
Return Type: DataPacket. Data returned in the data package depends on ReturnAllFields option. If
it‟s false then a reduced set of fields will be returned, similar to the GetEvents request. All records are
ordered by resource type and name.
Simplified data packet contains the following fields:
Column Data type Size
event_id Int 4
week_number Int 4
resource_type* Int 4
resource_id Int 4
resource_name Varchar 64
resource_unique_name Varchar 64
weeks Varchar 54
Utilities
41
Resource_Type can have 7 integer values representing each of available resources. ResourceTypes
enumeration list described above.
The full data packet contains the following fields:
Column Data type Size
event_id Int 4
week_number Int 4
room_layout_id* Int 4
Scheduling_status* Int 4
resource_type Int 4
resource_id Int 4
resource_name Varchar 64
resource_unique_name Varchar 64
Weeks Varchar 54
* Applicable to rooms only
SOAP method:
ResourceTypes ResourceType = Student;
WideString WeekDate = WideString(“2006-06-10T00:00:00”);
int ResourceID = 0;
bool IncludeParentEvents = false, ReturnAllFields = false, IncludeModules =
false, IncludeGroups = false, IncludeStaff = false, IncludeRooms = false,
IncludeStudents = false, IncludeEquipment = false, IncludeTeams = false;
AnsiString output = Test->GetResources(ResourceType, ResourceID, WeekDate,
IncludeParentEvents, ReturnAllFields, IncludeModules, IncludeGroups,
IncludeStaff, IncludeRooms, IncludeStudents, IncludeEquipment,
IncludeTeams);
delete WeekDate;
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetResources xmlns:NS1="urn:CELCAT">
<ResourceType xmlns:NS2="urn:MainForm1"
xsi:type="NS2:ResourceTypes">Student</ResourceType>
<ResourceID xsi:type="xsd:int">0</ResourceID>
<WeekDate xsi:type="xsd:string">2006-06-10T00:00:00</WeekDate>
<IncludeParentEvents xsi:type="xsd:boolean">false</IncludeParentEvents>
<ReturnAllFields xsi:type="xsd:boolean">false</ReturnAllFields>
<IncludeModules xsi:type="xsd:boolean">false</IncludeModules>
<IncludeGroups xsi:type="xsd:boolean">false</IncludeGroups>
<IncludeStaff xsi:type="xsd:boolean">false</IncludeStaff>
<IncludeRooms xsi:type="xsd:boolean">false</IncludeRooms>
<IncludeStudents xsi:type="xsd:boolean">false</IncludeStudents>
<IncludeEquipment xsi:type="xsd:boolean">false</IncludeEquipment>
<IncludeTeams xsi:type="xsd:boolean">false</IncludeTeams>
Utilities
42
</NS1:GetResources>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetResourcesResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:GetResourcesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.9 ResUniqueNameToID
Allows you to retrieve the ID of a particular resource based on the unique name field (assuming, that the
unique name column does not contain duplicate values). Returns the ID (as a string) that matches the
selected unique name, or an empty string when the resource of specified type and unique name does not
exist.
Parameters:
Data Type Name Comment
ResourceTypes ResourceTypes Enumeration value for student
(Student = 605)
WideString UniqueName Unique name field
Return Type: WideString. Expected result is the record‟s ID number (integer).
SOAP method:
ResourceTypes ResourceType = Student;
WideString UniqueName = “”;
WideString Result = Test->ResUniqueNameToID(ResourceType, UniqueName);
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ResUniqueNameToID xmlns:NS1="urn:CELCAT">
<ResourceType xmlns:NS2="urn:MainForm1"
xsi:type="NS2:ResourceTypes">Student</ResourceType>
Utilities
43
<UniqueName xsi:type="xsd:string">aaa</UniqueName>
</NS1:ResUniqueNameToID>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ResUniqueNameToIDResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">983</return>
</NS1:ResUniqueNameToIDResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.10 GetID
Generates a new primary key value that can then be safely inserted into any Timetabler database table.
It has been provided to allow 3rd party programmers to construct their own SQL insert statements and
safely run them against Timetabler’s database using a newly generated primary key value for each record
that they want to insert.
Parameters: none
Return Type: WideString. Expected result is the new primary key (integer value).
SOAP method:
WideString output = Test->GetID();
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetID xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
Utilities
44
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><NS1:Ge
tIDResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">48451</return>
</NS1:GetIDResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.11 SQLStatement
Allows you to submit SQL statements that will be run against the Timetabler database. It can be any SQL
statement that has syntax compatible with MS SQL Server implementation of the SQL. Extra care is
needed when submitting these statements, as they can be dangerous to the data definition and data itself
(drop statements and delete statements are also allowed).
Parameters:
Data Type Name Comment
WideString SQL SQL statement
Return Type: WideString. Expected result is either a datapackage (if the user submitted a valid SQL
select statement, or the word „OK‟ if the user submitted any other valid SQL statement, that doesn‟t
return a dataset (insert, update or data definition command – i.e. create, drop, alter)
SOAP method:
WideString input = “select top 1 * from CT_Student”;
WideString Result = Test->SQLStatement(input);
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:SQLStatement xmlns:NS1="urn:CELCAT">
<SQL xsi:type="xsd:string"> Select top 1 * from CT_Student </SQL>
</NS1:SQLStatement>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
Utilities
45
<NS1:SQLStatementResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:SQLStatementResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.12 Datapacket data type
The Datapacket result type is used in responses to all requests for multiple values. In particular, it is
applicable in the following requests: ListTimetables, GetEvents, GetResources and GetEventsFull. Its
structure is record-oriented – each row contains the same set of fields of the same data type. All
datapackets contain detailed information about its own structure (in its METADATA branch) as well as
record values. They could be fetched to a DataSet component/class without requiring parsing. The
following sample Datapacket XML contains a definition of 2 fields and 3 records.
<?xml version="1.0"?>
<DATAPACKET Version="2.0">
<METADATA>
<FIELDS>
<FIELD attrname="id" fieldtype="i4"/>
<FIELD attrname="name" fieldtype="string" WIDTH="20"/>
</FIELDS>
</METADATA>
<ROWDATA>
<ROW RowState="4" id ="1" name ="abc"/>
<ROW RowState="4" id ="2" name ="def"/>
<ROW RowState="4" id ="3" name ="ddd"/>
</ROWDATA>
</DATAPACKET>
6.7.13 Data packaging
The XML Server provides a mechanism that allows you to split large result sets into smaller data
packages and retrieve them when needed. In the CTXMLServerConfig application there is an option
entitled „Maximum XML package size‟ (specified in number of records). If the value is greater than zero,
then the whole result set is split into packages, none of which exceed the specified record count. The first
package is returned in response to the data request, and all subsequent data packages are buffered on
the server until they are cleared by a specific function, logout operation or submitting another data
request (in which case the old buffer will be cleared, and the new results buffered). All requests that
return datapacket data types will be affected by the Maximum XML package size value. The following
requests have been specified to support this package management:
6.7.14 GetPackagesCount
Allows you to retrieve a number of packages stored in the server‟s buffer. If buffers are empty the request
returns 0.
Parameters: none
Return Type: WideString. Expected result is the number of data packages stored on the server
(integer value).
SOAP method:
WideString Result = Test->GetPackagesCount();
Utilities
46
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetPackagesCount xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetPackagesCountResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">13</return>
</NS1:GetPackagesCountResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.15 GetPackage
Allows you to retrieve a selected data package from the buffer. Returns datapacket if the package can be
found, or an error message if not. Please note: The Metadata part of the package structure is included in
every datapacket.
Parameters:
Data Type Name Comment
Long Number Index of requested package
Return Type: DataPacket. Data returned in the data package depends on the ReturnAllFields option.
If it‟s false, then a reduced set of fields is returned (as with the GetEvents request). All records are
ordered by resource type and name. Expected result is the record‟s ID number (integer).
SOAP method:
long input = 2;
WideString output = Test->GetPackage(input);
XML Request:
<?xml version="1.0"?>
Utilities
47
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetPackage xmlns:NS1="urn:CELCAT">
<Number xsi:type="xsd:int">2</Number>
</NS1:GetPackage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:GetPackageResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string"></return>
</NS1:GetPackageResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.7.16 ClearPackages
Clears the data packets buffer on the server and releases the memory. It is not a mandatory method, but
we strongly advise you to call it once buffers are no longer needed (especially if buffers contain large
datasets and the 3rd party system allows for many simultaneous connections).
Parameters: none
Return Type: WideString. Expected result is the word “OK”.
SOAP method:
WideString Result = Test->ClearPackages();
XML Request:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ClearPackages xmlns:NS1="urn:CELCAT"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML Response:
Utilities
48
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<NS1:ClearPackagesResponse xmlns:NS1="urn:CELCAT">
<return xsi:type="xsd:string">OK</return>
</NS1:ClearPackagesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.8 Error Handling
In case of any error other than HTTP related requests, the XML Interface returns a detailed error
description in response to the request in the standard fault response format:
<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Fault>
<SOAP-ENV:faultcode>fault_code</SOAP-ENV:faultcode>
<SOAP-ENV:faultstring>fault_string – error message</SOAP-ENV:faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
All error messages should be either displayed to the user, or handled by the 3rd party system.
Fault code indicates where the fault was encountered. It is one of the following values:
Server application raised the exception before it was able to begin processing the request
or during processing.
Client application raised the exception because of an error in the SOAP request packet
that the client provided. For example, if the SOAP request packet specified a
nonexistent method or invalid parameter, the server specifies a FaultCode of
'Client'.
VersionMismatch application is a different version than the one that the SOAP request packet
specifies.
MustUnderstand application did not understand one of the SOAP headers in the request packet and
the request packet set its MustUnderstand header to indicate that the server must
handle all of its SOAP headers.
The fault string contains a message that could be displayed to user.
Utilities
49
6.8.1 Error list
For each of the requests, there are several possible error messages. They could be bound to TCP/IP
transport protocol, connection, XML syntax, improper parameters for requests, user‟s credentials,
database related and others.
Utilities
50
7. Bespoke Plugins
The CELCAT Timetabler 6 software provides a mechanism for integrating data from existing
management systems. This is achieved using bespoke „plugins‟ that are written by CELCAT to a
customer‟s specification. This section describes how such plugins work and may be useful in establishing
your requirements. For more up-to-date information, see our website www.celcat.com
7.1 Integration
Timetabler is used to construct and maintain teaching timetables. Although it is possible to add student
and course data directly into Timetabler, it is designed to cooperate with other software systems
including student management products so that existing data can be automatically incorporated. In
these circumstances, the other systems act as „origin‟ data sources; they are considered to be the master
source of the data provided to Timetabler.
For example, if you choose to integrate your Student Management Information System (SMIS) into
Timetabler, a plugin can be created that allows you to transfer student details from your SMIS to
Timetabler. The plugin operation can be invoked as often as is required to keep the Timetabler student
data in sync with the „master‟ data in your SMIS. Timetabler „knows‟ about the origin of its student data
and will always regard your SMIS as the last word on this!
So Software Integration Plugins are all about allowing you to designate other software systems as the
master source of some of your Timetabler data – an obvious example is that described above where your
student management system supplies Timetabler with a list of students. However, Software Integration
Plugins can do much more than that – they can be used to integrate enrolment data from your SMIS and
even event data from another timetabling package. Any number of plugins can be used to provide the
information Timetabler needs.
Note: Plugins usually provide a one-way data transfer mechanism; they do not facilitate the updating of
the origin data sources. However, depending upon your requirements, it may be feasible to transfer data
from Timetabler to a third-party system.
Example
One institution uses Timetabler to construct timetables and SMIS is the student management system.
The CELCAT bespoke plugin reads the SMIS database (say, on an Oracle database server) and, for each
student, extracts reference number, names, sex, title, date of birth, address, postcode, and home address
and phone number.
These details are then introduced to Timetabler. If the student already exists in Timetabler the details
are updated if necessary; otherwise the student is added. Timetabler „remembers‟ where the student
data came from and each time the plugin runs it synchronises the student data with the SMIS system
database. Furthermore, if a student has been removed from the SMIS, the plugin can remove the student
record from Timetabler (providing there are not extant registration marks, etc for the student).
Utilities
51
Tech Note - The data extraction uses a read-only ADO query to the SMIS database that involves a join
on the study_blocks, study_periods, study_block_associations and students tables.
The SMIS system (at this particular institution) is used to associate individual students with „study
blocks‟ that are akin to CELCAT Timetabler groups. So the plugin extracts this membership data and
introduces it to Timetabler.
The plugins allow the institution to operate their SMIS and Timetabling products in the knowledge that
any relevant changes made – e.g. new student enrolments, additional classes, etc - are reflected in the
timetable.
7.2 Specifying a Plugin
If you wish to specify requirements for a plugin, the first step is to complete the Timetabler Integration
Plugin Pro-Forma and then discuss your requirements with one of our representatives.
The latest version of the Pro-Forma can be found at the following location:
http://www.celcat.com/forms/CT6PluginProforma.pdf
Utilities
52
8. QLS Import/Export Plugin
This section describes one of the bespoke plugins that is supplied as part of the Timetabler software.
The CELCAT Timetabler QLS Plugin is used to transfer data between CELCAT Timetabler 6 and Agresso
QL Students (QLS) software, and is designed to allow the two systems to operate together on shared
data. The „plugin‟ is supplied as part of the CELCAT Timetabler 6 Client product and requires additional
software support from Agresso Ltd.
This document explains how to use the QLS Plugin and describes the data transfer mechanism it
implements. Note that the QLS Plugin has been designed for general-purpose use, and where the
functions it offers do not meet your needs you may wish to commission a bespoke plugin to cater for
your exact requirements – contact CELCAT for more information.
These notes are written from the perspective of a CELCAT Timetabler user, so we discuss importing
data from QLS and exporting data from Timetabler. A familiarity with CELCAT Timetabler 6 and
Agresso QLS is assumed. Finally, these notes have been compiled using the QLS Plugin supplied with
v6.2.0.17 of CELCAT Timetabler (with any service packs applied).
8.1 Running the Plugin
The QLS Plugin is available from the Tools menu of the CELCAT Timetabler Client software.
Select Tools | Timetable Utilities | Import to display the Import window as shown below. Then
select the Distinction QLS item (Agresso was formerly known as “Distinction Systems”).
Fig 34 - Import Window
The QLS Plugin comprises several tabbed pages each corresponding to a data type involved in the
import/export function. You can use the View menu to hide or display relevant pages (e.g. if you never
wish to import rooms into Timetabler you should hide the Room page).
Utilities
53
Fig 35 - QLS Plugin
These are the data types that can be imported / exported:
Import from QLS into CELCAT Timetabler
Departments, Sites, Room Layouts, Rooms, Fixtures, Staff, Students, Areas of Study
(“AOS”), Registers
Export from CELCAT Timetabler into QLS
Events
Fig 36 - Data Transfer
The transfer of data between Agresso QLS and CELCAT Timetabler is illustrated in the above diagram.
Utilities
54
8.2 Configuring the Plugin
Select the Tools | Options command to display the Options window as shown below.
Fig 37 - Options Window
Enable QLS Support
“QLS Support” must be enabled for your timetable before you can begin to transfer data between the
software systems.
Technical note: Ticking the “QLS Support” checkbox enables a trigger in the
Timetabler database called TG_EVENT_UPDATE_QLS. It is used to record
details of event changes in the CT_EVENT_LOG table, which in turn is required
when populating the list of changed events in the QLS Plugin‟s Event page.
QLS Academic Period
The QLS Academic Period refers to the academic period (or year) in the QLS database. When importing
data from QLS it is important to extract data that corresponds to the same time period as that of your
CELCAT timetable.
Auto Generate Register ID
When this option is ticked, a QLS register ID is automatically generated when a new event is added into
your timetable.
Technical note: The TG_EVENT_INSERT_QLS trigger is enabled when the “Auto generate
register ID” option is ticked. This performs the task of generating a register ID and inserting it
into the event‟s original_id field. The register ID is created by taking the event‟s internal unique
key value (an integer) and padding it to 12 characters using pseudo-random character values.
The QLS register ID associated with a Timetabler event can be displayed in Timetabler’s event window
for reference. See the Timetabler Client application (Tools | Options | General | Events | Show
original ID) as shown below.
Utilities
55
Fig 38 - Event Options
Include Suspended
When enabled, this option ensures that suspended events are also included in the Event page. The
default value is true.
Include Protected
When enabled, this option ensures that protected events are also included in the Event page. The
default value is true.
Use Event Module / Use Event Group
Specify whether CELCAT Timetabler modules or groups are used as the reference resource type when
listing and exporting events. Your choice will depend on how you use these entities in your timetable.
Other Options
Further options are available on some of the QLS Plugin‟s tabbed pages. These are described below:
Import Room Fixtures
This checkbox appears on the Room page and should be ticked if you want to transfer room
fixtures (items of equipment) from QLS into your timetable.
Active/Inactive/Both
This group of buttons appears on the AOS page and is used to specify what QLS Areas of Study
to import into Timetabler.
Import as Groups
This checkbox (on the AOS page) should be ticked if you want to import QLS Areas of Study as
CELCAT Timetabler Groups. If the checkbox is left unticked, they are imported as Modules.
Modified Since
On the Register page, the “Modified since” control allows you to limit the display of QLS
registers to those modified since the specified date (non-inclusive).
Similarly, on the Event page, the “Modified since” control allows you to limit the display of
Timetabler events to those modified since the specified date (non-inclusive). However, note
Utilities
56
that if more than one Timetabler event corresponds to a single QLS register and one of these
events has been changed since the specified date, all of these associated events will appear in
the list.
Register Description
Use these controls on the Event page to specify how the QLS register description should be
generated when exporting events from Timetabler.
Event Category
These controls on the Event page allow you to limit (by event category) the events that should
be displayed.
8.3 Data Mapping
Data is effectively shared between CELCAT Timetabler and Agresso QLS, which requires a well-defined
mapping of entities and their attributes between the two systems. The following table describes the
shared entities and shows their correspondences. The resource data (rooms, staff, etc) originates in QLS
and is only ever transferred one way (from QLS into Timetabler). However, the event data can be
transferred in both directions. This allows CELCAT Timetabler events to be used to generate register
headers in QLS, and QLS registers to be used to create events in Timetabler.
Technical note: In all cases, the CELCAT Timetabler origin_id and original_id
fields are used to record the origin of the record. For example, when a room is
imported from QLS, the room‟s code (as used to uniquely identify the room in
QLS) is stored in the room‟s original_id field (in Timetabler’s room record). The
QLS Plugin automatically creates a single origin_id value for all of your imported
records (allowing the QLS Plugin to distinguish between multiple import
sources). The result is that the QLS Plugin can easily match items and manage
subsequent changes to your imported records.
Departments
From Agresso QLS To CELCAT Timetabler Comments
Code or Description Name Either the QLS department code
or description is used depending
on your setting of the relevant
QLS export option
Code Original ID
Note that if you change a department‟s Name in Timetabler and re-run the QLS Plugin, the Name will
revert to its value in QLS. QLS is therefore considered the master source of department names.
Utilities
57
Rooms
From Agresso QLS To CELCAT Timetabler Comments
Code Unique name
Description Name
Telephone Telephone
Department code Department ID Via link to department entity
Site Site ID Via link to site entity
Area Area
Code Original ID
Note that when changes are made to any of the above room fields in Timetabler, these changes will be
overwritten the next time the QLS Plugin is run and the room imported. Thus QLS is considered the
master source of this room information. However, if other attributes of the room are modified in
Timetabler (such as the default capacity, access for the disabled, etc) then these attributes are retained.
Room Layouts
From Agresso QLS To CELCAT Timetabler Comments
Name + Description Name
Description Description
Name Original ID
When rooms are imported from QLS, any associated room layouts and capacities are also imported.
Although a single room in Timetabler can have multiple layouts, the QLS Plugin can only import a single
layout from QLS. If you add extra layouts for a room in Timetabler then these are retained and are not
overwritten when the QLS Plugin next runs and the room re-imported.
Sites
From Agresso QLS To CELCAT Timetabler Comments
Name Name Derived directly from the QLS
room record (the Site field)
rather than from a separate „Site‟
table
Name Original ID
A site is an attribute of the „room‟ entity. If the name of a site is changed in Timetabler, it can still be
matched by the unique_id field and is overwritten by the QLS data when the QLS Plugin is next run.
Utilities
58
Fixtures
From Agresso QLS To CELCAT Timetabler Comments
Description Name
Code Original ID
A fixture is a fixture or fitting in a room. See Inventory below. Note that the Fixtures and Inventory are
only imported from QLS if the Import room fixtures checkbox on the QLS Plugin‟s Room page is
ticked.
Inventory
From Agresso QLS To CELCAT Timetabler Comments
Room Code Room Original ID
Fixture Code Fixture Original ID
Quantity Quantity
A room inventory is the list of fixtures associated with each room.
Staff
From Agresso QLS To CELCAT Timetabler Comments
Code Unique name
Name Name
Honorific Title
Address Address1 The QLS staff address is
truncated to 64 characters and
placed in the Timetabler
address1 column
Department code Department ID Via link to department entity
Staff Office Room ID Via link to room entity
Home tel Home tel
WWW WWW
Code Original ID
Note that when changes are made to any of the above staff fields in Timetabler, these changes will be
overwritten the next time the QLS Plugin is run and the member of staff imported. Thus QLS is
considered the master source of this staff information. However, if other attributes of the staff record are
modified in Timetabler (such as the tag values, special needs flags, etc) then these attributes are
retained.
Utilities
59
Students
From Agresso QLS To CELCAT Timetabler Comments
Code Unique name
Name Name The QLS student name is
truncated to 64 characters
Date of birth Date of birth
Gender Sex
Code Original ID
If a student record is modified in Timetabler, your changes will be overwritten when the QLS Plugin is
next run and the student record imported. QLS is considered the master source of these student
attributes.
Areas of Study
From Agresso QLS To CELCAT Timetabler Comments
Code + Separator + Period Unique name Note the fabrication of the
unique identifier from aos code
and period of study separated by
the separator character
Description Name Course description truncated to
64 characters
Academic year Year
Department code Department ID Via link to department entity
WWW WWW
Code + Separator + Period Original ID
An “Area of Study” is QLS terminology and usually corresponds to a CELCAT Timetabler “Module” or
“Group” (depending upon your setting of the Import as groups checkbox in the QLS Plugin‟s AOS
page). QLS is considered the master source of AOS data.
Technical note: When importing resource records from QLS into Timetabler,
care is taken to ensure that inserts and updates are only performed when
absolutely necessary. For example, when importing a room from QLS, if it already
exists in Timetabler (as determined by the original_id value), the record will be
checked to see if any changes are required (i.e. field values have been modified in
QLS) and only updated if necessary.
Utilities
60
Registers
From Agresso QLS To CELCAT Timetabler Comments
Day of week Day of week
Start time Start time
End time End time
Department code Department ID Via link to department entity
Weeks Weeks
Register ID Original ID
When importing registers, the QLS Plugin matches registers against events using the QLS „Register ID‟.
This value is stored in the original_id field of Timetabler events. See below under “Registers and Events”
for more information.
Events
From CELCAT Timetabler To Agresso QLS Comments
Day of week Day of week
Start time Start time
End time End time
Register ID Register ID
Description Description
Department Department
Resource Assignments
Resource assignments are simply the lists of resources allocated to events/registers. These are
transferred when importing registers from QLS and when exporting events from Timetabler.
8.4 Registers and Events
The QLS Plugin provides for importing core resources (such as rooms, staff, etc) from QLS, but this data
is never exported back from Timetabler to QLS. The situation is different with event/register data, which
can be transferred in both directions. This section describes the way Agresso QLS „Registers‟ and
CELCAT Timetabler „Events‟ interact.
Utilities
61
8.4.1 QLS Registers
A QLS register comprises a register header identified by a „Register ID‟ and any number of associated
register profiles. Each profile contains detailed information about the register in a specified span of
contiguous weeks. Profile records never contain overlapping weeks. This arrangement is depicted below.
Fig 39
Additionally, each of the profiles contains a „fixed‟ set of resources that participate in the register in all
weeks of the profile.
8.4.2 CELCAT Timetabler Events
A Timetabler event occurs on a particular day of the week and at specified start and end times. It can run
in any of the weeks of your timetable (not just contiguous spans). Furthermore, resources (e.g. staff,
rooms etc) allocated to an event can participate in any or all of the event‟s weeks.
Often there is a one-to-one relationship between Timetabler events and QLS registers, but the above
description shows that this may not always be the case. For example, in the QLS register depicted above,
the three profiles could not be accommodated in a single event since they occur on different days (and at
different times). So when importing a register like this, the QLS Plugin must generate three events – one
for each of the profiles. The QLS Plugin manages the complexity of mapping registers to events and vice-
versa. In particular, when importing registers:
1. Profiles are matched against existing events and/or new events are created to
accommodate the data.
2. Extraneous events (which are no longer required to represent the register data) are
removed. Although this is not an error condition, a message is provided in the error log
when this happens.
When exporting events from Timetabler:
1. Care is taken to ensure that registers are created in QLS with contiguous week profiles and
where the resources are allocated in all weeks of the profile.
Utilities
62
The consequence of this is that you are free to split events in Timetabler (where the newly created events
will automatically retain the original register ID), allocate a resource to a subset of an event‟s weeks, etc,
without worrying about the transfer of the data to QLS – the Plugin manages this complexity for you.
An Event Export Example
The following example serves to illustrate how a complex Timetabler event is processed during the
export operation.
Part of the Timetabler event description:
Day Monday
Time 9:00 – 10:00
Weeks 1-10, 20-30
Rooms A101 (wks 1-5), B111 (wks 6-10, 20-30)
Staff Jones (wks 1-10), Smith (wks 20-30)
Note that the event has two non-contiguous week blocks (1-10 and 20-30), and that the event‟s resources
vary from week to week.
When exporting this event to QLS, the QLS Plugin partitions the event thus:
Weeks 1-5 (Room A101, Staff Jones)
Weeks 6-10 (Room B111, Staff Jones)
Weeks 20-30 (Room B111, Staff Smith)
These partitions correspond to the QLS register profiles that are created.
A Register Import Example
In this example, a QLS register is processed during the Import Register operation.
The QLS register comprises the following profiles:
Monday, 10:00-11:00, Weeks 1-5. Room X433, Staff Wright
Monday, 10:00-11:00, Weeks 10-20. Room X433, Staff Street
Wednesday, 10:00-11:00, Weeks 21-30. Room W277, Staff Wright
When importing this register into Timetabler, the QLS Plugin builds the following two events:
Monday, 10:00-11:00, Weeks 1-5, 10-20. Room X433, Staff Wright (wks 1-5), Street
(wks 10-20)
Wednesday, 10:00-11:00, Weeks 21-30. Room W277, Staff Wright
Note how the first two register profiles can be combined into a single event because the day and times
are identical.
Utilities
63
8.5 Filtering Lists
The QLS Plugin has a popup menu on each page that is accessed using the right mouse button. The
menus have commands to make selections, filter the lists according to certain criteria, etc. For example,
the Staff page popup menu shown below can be used to limit the list of QLS staff to those that have
changed (i.e. where the record values differ from those currently in your timetable).
Fig 40
8.6 Synchronising
Select the File menu, Synchronise command to run the QLS Plugin. The sequence of operations is as
follows:
1. Check for Duplicate Original ID Values
A check is performed to ensure that there are no duplicate original_id values for resources in
the Timetabler database.
Each resource record in Timetabler (room, staff etc) has a field called “original_id” which is
used in conjunction with an “origin_id” field to identify the origin of the record. When
resources are imported into Timetabler from QLS the original_id field is used to store an ID
value that uniquely identifies the record in QLS. It is therefore important that there are no
duplicate original_id value in the Timetabler records. If duplicates are found, details are
written to the error log and the whole process is aborted.
2. Import Departments
The QLS department records are imported. All departments are processed (there is no way to
select which departments to import). Departments are only imported if you have one or more of
the following pages enabled (not hidden): Room, Staff, Student, AOS.
Utilities
64
3. Import Sites
The QLS site records are imported (unless the Room page is hidden).
4. Import Room Layouts
The QLS room layout records are imported (unless the Room page is hidden). These are
simply the room layout types that are in use by the rooms that you wish to import. If you do not
select any rooms to be imported then no layouts will be processed either.
5. Import Rooms
The selected QLS rooms are imported.
6. Import Fixtures
The QLS equipment records are imported.
7. Import Inventory
The QLS inventory is imported (the details of the fixtures in each room).
8. Import Staff
The selected QLS staff records are imported.
9. Import Students
The selected QLS student records are imported.
10. Import Area of Study
The selected QLS „area of study‟ records are imported.
11. Import Registers
The selected QLS registers are imported, creating or updating events in Timetabler. Note that
when importing registers, if a resource assigned to the register does not exist it will be ignored.
12. Export Registers
The selected Timetabler events are exported to QLS, creating registers in QLS.
8.7 Errors
If errors are detected during the Synchronisation process, a log file is created which can be viewed using
the View menu, Error Log command.
There follows a list of the error messages that may appear in the log:
Field is too long and has been truncated
When importing data from QLS, if the value is too long to store in the CELCAT Timetabler database, it
will be truncated. The limitations are as follows:
Student names – 64 characters
AOS descriptions – 64 characters
Utilities
65
Events associated with register „xxx‟ have overlapping weeks. Register has not been
exported
Several Timetabler events are associated with the single register „xxx‟ (this can occur for example when
an event is split). You can only export one or more of these events if their weeks do not overlap.
Register „xxx‟ belongs to a department that doesn't exist in QLS
When exporting events to QLS, if an event belongs to a department that doesn‟t exist in QLS then the
above error is reported. Note that the event is still exported but without a department attribute.
No matching event was found for register: „xxx‟
When importing registers into CELCAT Timetabler, the above error is reported if more than one event
exists for a register, but the QLS Plugin has been unable to match the register to one of these events. A
„match‟ is based on a temporal comparison – day of the week, weeks and start/end times. This means
that the event‟s temporal attributes have been modified in CELCAT Timetabler. In these circumstances,
the QLS Plugin will create a new event for the register and discard the original event (unless the original
event is matched with another profile in the same register).
Another entry for register „xxx‟ was also found and included in the import procedure
When importing registers, a register ID may appear multiple times in the Register page. This is an
indication that the register contains a number of profiles (see above under “Registers and Events”). If
you select just one of these rows then the QLS Plugin automatically includes the other profiles too and
inserts the above information into the error log.
Another event for register „xxx‟ was also found and included in the export procedure
When exporting events, a number of listed events may correspond to a single register ID. If you have
only selected one of these rows then the QLS Plugin automatically includes other events with the same
register ID. This ensures that the complete „register‟ is transferred to QLS. Note that in some cases a
related event may not appear on the Event page because it hasn‟t been modified since the specified
„changed since‟ date. If this is the case, the QLS Plugin still detects the condition and automatically
includes all appropriate events for you.
Cannot update Room “ABC” – error message…
Cannot insert Room “ABC” – error message…
These messages (and variations) describe generic errors raised by the database server software. Please
see your SQL Server documentation for more information.
Duplicate Room record found – “ABC” (there are 2 duplicates)
This message (and variations) means that one or more of your Timetabler resource records have
duplicate original_id values. Each resource record in Timetabler (room, staff etc) has a field called
“original_id” which is used in conjunction with an “origin_id” field to identify the origin of the record.
When resources are imported into Timetabler from QLS the original_id field is used to store an ID value
that uniquely identifies the record in QLS. You should remove any duplication.
Event xxx preserved
Utilities
66
When registers are imported into Timetabler, sometimes an event is deemed superfluous and is
earmarked for removal. However, if there are any problems creating new event(s) for the register, then
the specified event is preserved.
The following event(s) were deleted during import of register…
This information message is used to list the IDs of events that have been deleted during the import of
registers into Timetabler.
8.8 Deleted Records
When resource data (rooms, staff etc) is deleted in QLS, the Plugin does not automatically remove any
corresponding data records in Timetabler. This is by design. If you need functionality that does not exist
in the QLS Plugin please contact us to discuss your requirements
Utilities
67
9. Timetabler COM Library
The CELCAT Timetabler 6 COM Library is a programming interface to the CELCAT Timetabler software
that can be used in most modern Windows programming environments, including VB, VBA, C++, C#,
ASP and Delphi. This document describes the library's Object Model.
NB – This Section (and much more comprehensive information) is available in on-line
help format called CT6ComLib.chm
The COM Library
The library is implemented as an in-process OLE Automation Server (also known as an 'Active X' or
'COM' Library). It is provided as a single file (called CT6Lib.dll) that you can distribute to users of your
software.
The key to successfully using the library is an understanding of the library's object model - a hierarchy of
objects containing methods and properties that read and write timetable data.
High-Level Objects
As you may know, CELCAT publishes a description of the Timetabler relational database. However, for
most operations, you don't need to understand the complexities of this database schema in order to use
the COM library - the COM objects provide a level of abstraction from the database that makes it easy to
generate timetables, add events, etc without a knowledge of the underlying data structures. Once you
become familiar with one or two of the Timetabler objects you should quickly grasp how to use new
objects you come across.
In this documentation, objects are sometimes referred to using the name of the interface
implementation (e.g. ICT6DataSet); but are usually abbreviated (e.g. CT6DataSet or simply DataSet).
The terms are identical.
Example Code
Where possible simple examples are given using the Microsoft Visual Basic language and employing
early binding of objects (although late binding is also supported).
The examples are usually fragments of code and are not meant to represent commercial-strength coding
techniques. For example, MsgBox() is used to display results in a simplistic way and error handling is
often omitted (error handling should normally be performed using exceptions and VB try/catch blocks).
To make direct use of the example code you may need to translate it into your development language.
9.1 Getting Started
To get started with the CELCAT Timetabler COM Library:
1. Installing Development Files
The files can be found on your CELCAT Timetabler installation CD in the Client\COMLibrary folder.
Utilities
68
Copy borlndmm.dll to a location on your path (when installing CELCAT applications the file is normally
installed in the same folder as the application). For development purposes you may choose to install it in
the Windows or System folder.
Copy the following files to a path on your system or to the Windows system folder (usually named
"system32"):
cc3260mt.dll
stlpmt45.dll
ct6lib.dll
midas.dll
CT6Lib.dll
2. Register Selected Files
The CT6Lib.dll and midas.dll files should be registered on your development machine using a command-
line Microsoft utility called regsvr32.exe. Just open a command prompt window, navigate to the folder
where the files are stored and run regsvr32 as follows:
regsvr32 midas.dll
regsvr32 CT6Lib.dll
3. Access to Timetabler Server
The COM Library uses a server application called CELCAT Timetabler Server (see Architecture). You
will need to either install this application on your development machine or ensure you have access to it
(refer to the Timetabler Installation instructions). This may mean registering the Timetabler Server type
library if no other CELCAT Timetabler applications are installed on your machine. Use Microsoft's
regtlib.exe to do this if required.
4. Sample Data
Ensure that you have a suitable database to develop with (perhaps a copy of your real timetable).
Furthermore, ensure that the timetable database is enabled for COM Library use (See the Timetabler
Administrator, Settings page).
5. Administrator Credentials
Get a user name and password that you can use in development. These must have administrator access
rights and can be configured using the CELCAT Timetabler Administrator application.
6. Register the COM Library
Before you can use the Timetabler COM Library (with early binding of objects) you need to 'register' the
library with your development environment. How you do this depends upon the development tools that
you are using. In Visual Basic 2005, for example, you should use the Project menu, Add References
dialog, open the COM page and add "CT6Lib Library" file to your list of available references. In other
Utilities
69
development environments, you may need to "Import a type library" or "Add a COM Library" – please
consult your documentation for further details.
7. Examine Sample Applications
A good place to start is with the sample applications that are available on our web site
(http://www.celcat.com/products/timetabler/com_library.html)
9.2 Objects
There follows a brief description of the Timetabler objects contained in the CT6Lib library. Brief sample
code is provided for most items. For more detailed information please see the special sections on each
object. The objects are listed in the order you are most likely to use them.
Sample Code
Note that the sample code shown below has been compiled in VB 2005. Early binding is used throughout
(although you can use late binding if required). Object declaration is generally explicit, but you can use
property chaining if you wish, e.g. the following two code snippets are functionally identical:
Snippet 1.
Dim Config As CT6Lib.ICT6Configuration = Session.Configuration
MsgBox(Config.PeriodCount)
Snippet 2.
MsgBox(Session.Configuration.PeriodCount)
Note that ellipses are used to indicate where code has been elided.
9.2.1 CT6Session
This is the most important object and the only one that can be directly created by your application (i.e.
CT6Session is a 'CoClass' and can be created using the 'New' keyword in VB). You can think of
CT6Session as representing the top-level CELCAT Timetabler application itself, and all other objects are
directly or indirectly accessible from it. Here's some sample code showing how a session is created. In
this example:
1. A new CT6Session variable called 'Session' is created
2. The session is initialised with the name of the computer on which the Timetabler Server
runs (in this case "MARVIN")
3. The session logs into a timetable database called "2006_Timetable" on a SQL Server called
"GORT". The Timetabler user name and password are also supplied.
4. The session is logged out
5. The session is unitialised
6. The session is freed
Try
Dim Session As New CT6Lib.CT6Session
Session.Init("MARVIN")
Utilities
70
Session.Login("GORT", "2006_Timetable", "Administrator", "password")
Session.Logout()
Session.UnInit()
Session = Nothing
Catch ex As Exception
MsgBox(ex.Message)
End Try
9.2.2 CT6Databases
The CT6Databases object is used to determine which timetable databases are available from your chosen
Timetabler Server. The CT6Databases object is available from the CT6Session object. The following code
shows how to iterate through the list of timetables.
Dim Databases As CT6Lib.ICT6Databases = Session.Databases
While Not Databases.AtEnd
MsgBox(Databases.TimetableName)
Databases.Next()
End While
Note the use of the AtEnd property and Next method. These are used extensively in library collections
(along with First, Last, Prior and Count).
9.2.3 CT6Configuration
The CT6Configuration object represents the basic parameters of the current timetable (e.g. timetable
name, number of weeks, etc). The CT6Databases object is available from the CT6Session object. In the
following example the number of periods per day is displayed.
... (login to a timetable)
Dim Config As CT6Lib.ICT6Configuration = Session.Configuration
MsgBox(Config.PeriodCount)
Note that it is not possible to modify a timetable's configuration using the CT6Configuration object. This
should only be attempted using the Timetabler Administrator application.
9.2.4 CT6EntityType
The CT6EntityType object represents a Timetabler entity type, e.g. Room, Module, etc. It is not a
particular entity; rather it denotes the whole entity type within Timetabler. For example, if you want to
perform an operation on rooms then the first thing you probably need is a CT6EntityType object
representing the rooms in your timetable. You can get a CT6EntityType object from CT6Session for the
following Timetabler entities: Modules, Rooms, Staff, Groups, Student, Equipment, Teams,
Departments, Faculties, Courses, Room Layouts, Fixtures, Event Categories, Sites and Events.
In the following example, the room name is displayed that corresponds to the internal CELCAT ID =
18286
Dim Rooms As CT6Lib.ICT6EntityType = Session.Room
MsgBox(Rooms.GetNameFromID(18286))
In the next example, the member of staff "Andrews, Lee" is deleted:
Utilities
71
Dim Staff As CT6Lib.ICT6EntityType = Session.Staff
Staff.Delete(Staff.GetIDFromUniqueName("Andrews, Lee"))
9.2.5 CT6DataSet
The CT6DataSet object is used extensively in the library and provides a means of viewing and modifying
timetable data. It is a generic object which can represent different types of data, i.e. whether you are
considering modules, rooms, events etc, you will use a CT6DataSet object to manage the data. The object
has many methods and properties which may or may not be applicable depending upon the context in
which CT6DataSet is used.
The example shown below demonstrates how to search for a member of staff and modify her telephone
number. Here's what happens:
1. A CT6DataSet object is created to hold staff data. The CreateDataSet method takes a
boolean parameter, 'False' indicating that the DataSet is not read-only
2. Before the DataSet is opened, a DataSet filter is specified to limit the data to a single staff
record - that of Jane Taylor
3. The DataSet is opened
4. We check that the DataSet is not empty (if it is empty this means that Jane's record could
not be found)
5. The DataSet is placed in edit mode
6. The Tel1 property is modified
7. The data is posted then saved
Dim StaffData As CT6Lib.ICT6DataSet = Session.Staff.CreateDataSet(False)
StaffData.Filter.ByUniqueName("Taylor, Jane")
StaffData.Open()
If Not StaffData.AtEnd Then
StaffData.Edit()
StaffData.Tel1 = "024 7646 9930"
StaffData.Post()
StaffData.Save()
End If
9.2.6 CT6Filter
The CT6Filter object is available from the CT6DataSet object and allows you to filter the contents of the
DataSet. For example, if you want to retrieve all of the group records within a certain department you
would use the CT6Filter.ByDeptID or CT6Filter.ByDeptName property. See the following example, in
which all of the groups in the "Art and Design" department are listed:
Dim GroupData As CT6Lib.ICT6DataSet = Session.Group.CreateDataSet(True)
GroupData.Filter.ByDeptName("Art and Design")
GroupData.Open()
While Not GroupData.AtEnd
MsgBox(GroupData.Name)
GroupData.Next()
End While
Utilities
72
9.2.7 CT6Membership
The CT6Membership object represents membership data in your timetable (the relationship between
groups, subgroups and students). It is used in conjunction with the CT6MembershipData object to
provide a read-only view of the data (if you want to modify the membership structures you should use
the appropriate CT6EntityType and CT6DataSet).
9.2.8 CT6MembershipData
CT6MembershipData is used in conjunction with CT6Membership to provide read-only access to the
group/subgroup/student membership data. In Timetabler 6 this membership hierarchy can be complex
with groups and students nested at any level in a tree-like structure. The CT6MembershipData object
makes it easy to extract, for example, all of the 'child' groups for a given group.
In the following example a 'descendant groups' DataSet is created for the "Elec Eng 1" group - it contains
all of the groups, sub-groups, sub-sub-groups etc for "Elec Eng 1"
Dim Membership As CT6Lib.ICT6Membership = Session.Membership
Dim MembershipData As CT6Lib.ICT6MembershipData = _
Membership.CreateDescendantGroupsDataSet(Session.Group.GetIDFromUniqueName("
Elec Eng 1"))
While Not MembershipData.AtEnd
MsgBox(Session.Group.GetUniqueNameFromID(MembershipData.ID))
MembershipData.Next()
End While
9.2.9 CT6Timetable
The CT6Timetable object is used to extract read-only event information for selected resources. It is
available from the CT6EntityType object and is the object to use if you need to produce a timetable for a
member of staff, room, etc. See also the CT6TimetableFilter, CT6TimetableInclude and
CT6TimetableDetail objects.
The following example shows how to generate a timetable for a member of staff:
1. A CT6Timetable object is created for the staff entity
2. The timetable's 'Filter' object is used to specify the relevant member of staff
3. The event order is specified (determining the order in which events are stored in the
CT6Timetable object)
4. The timetable's 'Include' object is used to stipulate which event resource types should be
included in the returned data
5. The timetable is opened and the event data displayed
Dim Timetable As CT6Lib.ICT6Timetable = Session.Staff.CreateTimetable()
Timetable.Filter.AddResource(Session.Staff.GetIDFromUniqueName("Taylor,
Jane"))
Timetable.EventOrder = CT6Lib.EventOrder.CT6LIB_DAY_TIME_WK
Timetable.Include.AddDetailType(CT6Lib.EntityType.CT6LIB_ROOM)
Timetable.Open()
While Not Timetable.AtEnd
MsgBox(Timetable.EventText)
Timetable.Next()
End While
Utilities
73
9.2.10 CT6Weeks
The CT6Weeks object represents the weeks in a timetable database. Typically it is used to specify which
weeks are active or inactive for timetable operations.
In this example, the CT6Weeks object is used to specify which weeks of a timetable should be included in
the event filter (in this case only 1 week):
Dim Timetable As CT6Lib.ICT6Timetable = Session.Staff.CreateTimetable()
Timetable.Filter.AddResource(Session.Staff.GetIDFromUniqueName("Taylor,
Jane"))
Timetable.Filter.Weeks.Clear()
Timetable.Filter.Weeks.SetActive(Session.Configuration.GetWeekForDate(DateVa
lue("6 November 2006")), True)
Timetable.EventOrder = CT6Lib.EventOrder.CT6LIB_DAY_TIME_WK
Timetable.Include.AddDetailType(CT6Lib.EntityType.CT6LIB_ROOM)
Timetable.Open()
While Not Timetable.AtEnd
MsgBox(Timetable.EventText)
Timetable.Next()
End While
9.2.11 CT6TimetableFilter
The CT6TimetableFilter object is used in conjunction with the CT6Timetable object to limit the events
that are returned when the CT6Timetable object is opened. It can be used to specify weeks, days, times,
resources, etc.
9.2.12 CT6TimetableInclude
The CT6TimetableFilter object is used in conjunction with the CT6Timetable object to specify the
information about each event that is included when the CT6Timetable object is opened. For example, it
can be used to specify whether room and staff assignments are included.
9.2.13 CT6TimetableDetail
The CT6TimetableDetail object represents the event assignment data associated with a CT6Timetable
object, i.e. the details of the resources allocated to each event. In the following example, a
CT6TimetableDetail object (called 'RoomDetail') is used to display information about the rooms
allocated to each event:
Dim Timetable As CT6Lib.ICT6Timetable = Session.Staff.CreateTimetable()
...
Timetable.Open()
While Not Timetable.AtEnd
While Not Timetable.RoomDetail.AtEnd
MsgBox(Timetable.RoomDetail.UniqueName & " weeks " &
Timetable.RoomDetail.WeekText)
Timetable.RoomDetail.Next()
End While
Timetable.Next()
End While
Utilities
74
9.2.14 CT6Stats
The CT6Stats object is used in conjunction with the CT6StatsConfig and CT6StatsBreakdown objects to
extract statistical information from your timetable data. It is available from the CT6EntityType object.
In the following example, stats are calculated for a member of staff - Jane Taylor, displaying the total
amount of time in her timetable. (note that event category weightings are applied to the calculation and
the weekend has been removed from the analysis):
Dim Stats As CT6Lib.ICT6Stats = Session.Staff.CreateStats()
Stats.Config.ShouldWeight = True
Stats.Config.RemoveDayOfWeek(CT6Lib.DayOfWeek.CT6LIB_SAT)
Stats.Config.RemoveDayOfWeek(CT6Lib.DayOfWeek.CT6LIB_SUN)
Stats.ResourceID = Session.Staff.GetIDFromUniqueName("Taylor, Jane")
Stats.Calculate()
MsgBox(Stats.TotalTimeAsText)
9.2.15 CT6StatsConfig
The CT6StatsConfig object is available from the CT6Stats object and is used to specify calculation
parameters. See under CT6Stats for more information.
9.2.16 CT6StatsBreakdown
The CT6StatsBreakdown object is used to access any stats breakdown information that is provided by
the CT6Stats calculation routine. In the example shown below the breakdown type has been set to
'Module':
Dim Stats As CT6Lib.ICT6Stats = Session.Staff.CreateStats()
...
Stats.Config.BreakdownType = CT6Lib.EntityType.CT6LIB_MODULE
Stats.Calculate()
MsgBox(Stats.TotalTimeAsText)
While Not Stats.Breakdown.AtEnd
MsgBox(Stats.Breakdown.Name & " - " & Stats.Breakdown.TotalTimeAsText)
Stats.Breakdown.Next()
End While
9.2.17 CT6Attendance
The CT6Attendance object provides read-only access to register marks. In the example shown below,
register marks are filtered by department, by member of staff and then by date range. Then for each
register found, the marks are displayed for each student:
Dim Attendance As CT6Lib.ICT6Attendance = Session.Attendance
Attendance.Filter.AddDept(Session.Department.GetIDFromName("Art and
Design"))
Attendance.Filter.AddStaff(Session.Staff.GetIDFromUniqueName("Taylor,
Jane"))
Attendance.Filter.StartDate = DateValue("6 November 2006")
Attendance.Filter.EndDate = DateValue("10 November 2006")
Attendance.Open()
While Not Attendance.AtEnd
Dim Marks As CT6Lib.ICT6AttendanceMarks = Attendance.CreateMarksDataSet()
While Not Marks.AtEnd
MsgBox(Marks.StudentName & " - " & Marks.MarkAbb)
Utilities
75
Marks.Next()
End While
Attendance.Next()
End While
9.2.18 CT6AttendanceFilter
The CT6AttendanceFilter object is used to filter the registers that are returned in the CT6Attendance
object. See CT6Attendance for more information.
9.2.19 CT6AttendanceMarks
The CT6AttendanceMarks object represents a list of marks in a register. It is available from the
CT6Attendance object.
9.2.20 CT6ClientListener
The CT6ClientListener object provides a means of gaining feedback during lengthy operations. The
object is unusual in that it should be created in the client application and a reference to it passed to the
COM Library. When this is done it is possible for the library functions to 'callback' to your application so
that you can provide a progress indicator, etc.
9.2.21 CT6Utils
The CT6Utils object contains several utility methods.
9.2.22 CT6RecordCache
The CT6RecordCache object is used to access basic and frequently-used data. As its name suggests, the
CT6RecordCache object stores (or caches) data in your application so that it does not need to request it
from the database each time it is needed.
9.2.23 CT6IDList
The CT6IDList object is used to store lists of ID values.
9.2.24 CT6ImportCache
The CT6ImportCache object is used to store in-memory copies of existing Timetabler data during import
operations.
9.2.25 Low Level Objects
The high-level COM Library objects described above provide control over most aspects of the Timetabler
data. However, some low-level objects are provided so that you can have complete control. Use of the
following low-level objects requires knowledge of the CELCAT Timetabler 6 database. There is a
potential for mistakes that will wreck your timetable database - proceed with care!
9.2.26 CT6Command
The CT6Command object can be used to execute any SQL command against your database.
Utilities
76
9.2.27 CT6DatabaseMetaData
The CT6DatabaseMetaData object provides a read-only view of the Timetabler database schema. It can
be used to list all of the table names, column names etc.
9.2.28 CT6DataSet
When you create a CT6DataSet object directly from the CT6Session object then you can open any SQL
statement you wish on your database.
Trademarks:
"Microsoft” and “Windows” are either registered trademarks or trademarks
of Microsoft Corporation in the United States and/or other countries.
“Adobe” and “Acrobat” are either registered trademarks or trademarks of
Adobe Systems Incorporated in the United States and/or other countries.
“Novell” is either a registered trademark or trademark of Novell, Inc
Incorporated in the United States and/or other countries.
Copyright © 2008 CELCAT
Release 3, November 2008