seantis.reservation 1.0.5

Create the Site

Having started your instance, navigate to the plone root:

http://localhost:8080

It should say ‘Plone is up and running’. On this site click “Create new Plone site” If you used the develop.cfg the username and password are “admin” and “admin”.

Obviously you do not want to use develop.cfg in production!

On the “Create a Plone site” form, you should enter name and title of your plone site, followed by checking the box of the following Add-On:

Seantis Reservation - for default plone theme

Having done that, click “Create Plone Site”

Create Resource Folder

On your freshly minted Plone Site, click on “Add new…” and choose “Folder”. Use any name you like.

Add a Resource

In the newly created folder, click on “Display” and choose “Resource Listing”.

This will turn the folder into a view designed for displaying Resources.

After changing the view click on “Add new…” and choose “Resource”. Enter any name you like.

You should now see a calendar in which you can create allocations that may be reserved. One level up, in the folder view, you may add more resources and compare them. Of course there is more to learn, but this is the basic setup of the Seantis Reservation module.

Resource

Resources are Dxterity content types who display a calendar and interact with the core of seantis.reservation. They are heavy on the UI side of things, while being nothing more than a foreign key in the database.

Allocations

Everyone familiar with Outlook or Google Calendar knows that one can just click on an empty spot and add a new reservation.

In seantis.reservation this is not the case. In this module, a spot that may be reserved must be marked as such first. This is called an allocation.

The idea is to allocate time which may be reserved. It is like declaring time that should be managed by reservations. Outlook and Google Calendar implicitly see all time as allocated and under their management.

One reason for this is the fact that only through limiting the available time we can calculate meaningful utilization numbers. Another reason is that some periods of time may be overbooked, other times may not, or generally speaking: some timeperiods are different than others.

Allocations therefore define how periods of time may be reserved. They may not overlap for any given resource and they are independent of Plone and part of the SQL database model.

Reserved Slots

When reserving an allocation or a part of an allocation, reserved slots are generated. They ensure that no reservation is ever granted twice by accident.

Reserved slots may start every 5 minutes. At 5.35 or 5.40 for example, but not at 5.36 or 5.39. When reserving 45 minutes of an allocation, many reserved slots are spawned and aligned. Their primary keys then ensure on a low level basis that no overlaps occur.

For a much needed example:

Resource: 1234
Allocation: 09:00 - 10:00

=> reserve 1234, 09:30 - 10:00

Reserved Slots:
    1234 09:30
    1234 09:35
    1234 09:40
    1234 09:45
    1234 09:50
    1234 09:55

=> try to reserve 1234, 09:30 - 10:00 again

Reserved Slot 1234, 09:30 already exists

Of course there are a number of optimizations to ensure that we don’t generated millions of reserved slots. But this is basically it.

Reservations

Reservations exist in two states: Pending and Approved.

Pending reservations are reservations on a waitinglist. Users have submitted them, but nobody has confirmed them. They have therefore no reserved slot associated with them.

Approved reservations are reservations who are associated with reserved slots and are therefore confirmed and binding.

Note that it is possible in the UI side of seantis.reservation to go from pending to confirmed automatically. This is called auto-approval.

Why is Database X not an option? / Why does Postgresql < 9.1 not work?

seantis.reservation relies on a Postgresql feature introduced in 9.1 called “Serialized Transactions”. Serialized transactions are transactions that, run on multiuser systems, are guaranteed to behave like they are run on a singleuser system.

In other words, serialized transactions make it much easier to ensure that the data stays sane even when multiple write transactions are run concurrently.

Other databases, like Oracle, also support this feature and it would be possible to support those databases as well. Patches welcome.

Note that MySQL has serialized transactions with InnoDB, but the documentation does not make any clear guarantees and there is a debate going on:

http://stackoverflow.com/questions/6269471/does-mysql-innodb-implement-true-serializable-isolation

Why did you choose SQL anyway? Why not use the ZODB? Why not insert your favorite NoSQL DB here?

• If a reservation is granted to you, noone else must get the same grant. Primary keys and transactions are a natural fit to ensure that.

• Our data model is heavily structured and needs to be validated against a schema.

• All clients must have the same data at all time. Not just eventually.

• Complicated queries must be easy to develop as reporting matters.

• The core of seantis.reservation should eventually be independent of Zope/Plone.

Why / How is my allocation colored? My allocation is green, but it should be orange/red!

Basically colors are assigned to events based on their availability:

75-100% : Green / Available

1-74% : Orange / Partly Available

0% : Unavailable

The availability is calculated by taking the total time available and dividing it by the time reserved. If an allocation is set to be approved automatically (the default) a 0% availability also means that no new reservations can be made.

If an allcation is set to be approved manually, there’s automatically an unlimited waitinglist. Reservations to that waitinglist can be made at any time - unless the allocation setting is changed - and the number of people in the waitinglist is shown on the allcation itself.