CELCAT® Timetabler 6downloads.celcat.com/forms/Dec08/F_Utilities.pdf · Welcome to CELCAT...

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.

http://www.celcat.com/support/useful_documents/useful_documents.html

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 <

> &amp respectively. In the case of responses, a similar rule is applicable: all occurrences of <, >,

&amp 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:









<NS1:GetDefaultCTServerResponse xmlns:NS1="urn:CELCAT">

<return xsi:type="xsd:string">MYMACHINE:CTTServer.CELCAT_TT_Server</return>

</NS1:GetDefaultCTServerResponse>

</SOAP-ENV:Body>


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:









<NS1:ListTimetables xmlns:NS1="urn:CELCAT"/>

</SOAP-ENV:Body>


XML Response:









<NS1:ListTimetablesResponse xmlns:NS1="urn:CELCAT">

<return xsi:type="xsd:string"></return>

</NS1:ListTimetablesResponse>

</SOAP-ENV:Body>


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:








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>


XML Response:









<NS1:LogInResponse xmlns:NS1="urn:CELCAT">

<return xsi:type="xsd:string">OK</return>

</NS1:LogInResponse>

</SOAP-ENV:Body>


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


Utilities

34

SOAP method:

WideString Result = Test->LogOut();

XML Request:









<NS1:LogOut xmlns:NS1="urn:CELCAT"/>

</SOAP-ENV:Body>


XML Response:









<NS1:LogOutResponse xmlns:NS1="urn:CELCAT">


</NS1:LogOutResponse>

</SOAP-ENV:Body>


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:


WideString UserName CELCAT user name

Return Type: DataPacket. Data returned in the data package – below:


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:









<NS1:GetUserRoles xmlns:NS1="urn:CELCAT">

<UserName xsi:type="xsd:string"></UserName>

</NS1:GetUserRoles>

</SOAP-ENV:Body>


XML Response:









<NS1:GetUserRolesResponse xmlns:NS1="urn:CELCAT">


</NS1:GetUserRolesResponse>

</SOAP-ENV:Body>


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:


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:









<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>


XML Response:









<NS1:ValidateUserResponse xmlns:NS1="urn:CELCAT">


</NS1:ValidateUserResponse>

</SOAP-ENV:Body>


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:


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:


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:


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



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:


Utilities

39








<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>


XML Response:






ENC="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body SOAP-


<NS1:GetEventsResponse xmlns:NS1="urn:CELCAT">


</NS1:GetEventsResponse>

</SOAP-ENV:Body>


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:



(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:


event_id Int 4

week_number Int 4

resource_type* Int 4

resource_id Int 4



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:


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



Weeks Varchar 54

* Applicable to rooms only

SOAP method:


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:









<NS1:GetResources xmlns:NS1="urn:CELCAT">



<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>


XML Response:









<NS1:GetResourcesResponse xmlns:NS1="urn:CELCAT">


</NS1:GetResourcesResponse>

</SOAP-ENV:Body>


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:



(Student = 605)

WideString UniqueName Unique name field

Return Type: WideString. Expected result is the record‟s ID number (integer).

SOAP method:


WideString UniqueName = “”;

WideString Result = Test->ResUniqueNameToID(ResourceType, UniqueName);

XML Request:









<NS1:ResUniqueNameToID xmlns:NS1="urn:CELCAT">



Utilities

43

<UniqueName xsi:type="xsd:string">aaa</UniqueName>

</NS1:ResUniqueNameToID>

</SOAP-ENV:Body>


XML Response:









<NS1:ResUniqueNameToIDResponse xmlns:NS1="urn:CELCAT">

<return xsi:type="xsd:string">983</return>

</NS1:ResUniqueNameToIDResponse>

</SOAP-ENV:Body>


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:









<NS1:GetID xmlns:NS1="urn:CELCAT"/>

</SOAP-ENV:Body>


XML Response:







Utilities

44


ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><NS1:Ge

tIDResponse xmlns:NS1="urn:CELCAT">


</NS1:GetIDResponse>

</SOAP-ENV:Body>


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:


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:









<NS1:SQLStatement xmlns:NS1="urn:CELCAT">

<SQL xsi:type="xsd:string"> Select top 1 * from CT_Student </SQL>

</NS1:SQLStatement>

</SOAP-ENV:Body>


XML Response:










Utilities

45

<NS1:SQLStatementResponse xmlns:NS1="urn:CELCAT">


</NS1:SQLStatementResponse>

</SOAP-ENV:Body>


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.


<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:









<NS1:GetPackagesCount xmlns:NS1="urn:CELCAT"/>

</SOAP-ENV:Body>


XML Response:









<NS1:GetPackagesCountResponse xmlns:NS1="urn:CELCAT">


</NS1:GetPackagesCountResponse>

</SOAP-ENV:Body>


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:


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:


Utilities

47








<NS1:GetPackage xmlns:NS1="urn:CELCAT">

<Number xsi:type="xsd:int">2</Number>

</NS1:GetPackage>

</SOAP-ENV:Body>


XML Response:









<NS1:GetPackageResponse xmlns:NS1="urn:CELCAT">


</NS1:GetPackageResponse>

</SOAP-ENV:Body>


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


SOAP method:

WideString Result = Test->ClearPackages();

XML Request:









<NS1:ClearPackages xmlns:NS1="urn:CELCAT"/>

</SOAP-ENV:Body>


XML Response:

Utilities

48









<NS1:ClearPackagesResponse xmlns:NS1="urn:CELCAT">


</NS1:ClearPackagesResponse>

</SOAP-ENV:Body>


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:






ENC="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body SOAP-


<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>


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


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


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


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


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


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


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


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


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


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


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


Day of week Day of week

Start time Start time

End time End time


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")

http://www.celcat.com/products/timetabler/com_library.html

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):


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()


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:


...

Timetable.Open()


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

CELCAT® Timetabler 6downloads.celcat.com/forms/Dec08/F_Utilities.pdf · Welcome to CELCAT...

Documents

Transcript of CELCAT® Timetabler 6downloads.celcat.com/forms/Dec08/F_Utilities.pdf · Welcome to CELCAT...