TolfaWeb

by Gisle Hannemyr

This is the design document (work in progress) of TolfaWeb. This is a new service designed to replace the existing Tolfa Booking System (TBS) that is used by the Tolfa Assocation to manage facility bookings and content management.

Table of contents

1. Introduction

NOTE: This document is in English because I communicate with developers overseas and consequently would like to be able to supply them with system documentation in English. The service, when delivered to the client, will have a Norwegian user interface, and the end user documentation will be in Norwegian.

CAVEAT: This is a working document written by the designer for himself (as part of the system documentation). While it may be shared with the Tolfa Association for purposes of discussion, it is not intended as end user documentation. Do not expect to understand everything in this document. However. I shall be happy answer any questions you may have about this document, and about the service (TolfaWeb).

TolfaWeb is defined as service (rather than a system) because it will implemented as a “SaaS” (“Software as a Service”). In addition to the necessary credentials (e.g. a username and password) all you will need to access the TolfaWeb is a connection to the Internet, and a PC or tablet with a standard web browser.

TolfaWeb will leverage on the Resource Booking Grid (hereafter RBG). This is a Drupal custom project (developed by Hannemyr Nye Medier AS), that creates a grid-object suitable for booking. There exists classes in RBG) that can be populated through the GUI to create TolfaWeb. For an overview these see section 4 (Classes and attributes).

2. Design goals

The overarching design goals for TolfaWeb are that the new service:

  1. Capable (by extending RBG through the GUI) of supporting all booking-types, pricing plans and policies in the existing TBS;
  2. enables the use of seasonal rebates to encourage use of the facility in the low season;
  3. enables the addition of new policies to limit abusive bookings (see separate design document);
  4. enables a web content management service (WCMS), for posting news and announcements on the booking website.

To meet the first 3 design goals, the designer has studied various commercial booking systems, as well as other software (commercial and free) to determine how these design goals can be met. The conclusion is that no pre-existing software, system or service can meet these design goals.

These compoents of TolfaWeb will therefore be created from scratch, or by extending RBG.

The last goal (enable an WCMS) can however be met by Drupal (a standard and widely used WCMS). ToldaWeb will be seamlessly integrated with Drupal, and available along with the WCMS on the Tolfa Assocation's website.

3. Prices and policies

A special feature of the TBS is the existence of booking types. This feature is missing from all other booking systems I've studied, but is a requirement for TolfaWeb. In TolfaWeb, the same bed/room is rented at different prices depending on the type of booking.

In the TBS, booking types are fixed in code. In TolfaWeb booking types shall be added and removed by the booking master through the GUI. (The term “GUI” an acronym for “Graphical User Interface”. It is an interface where the user interacts with computers graphic screen by direct manipulation, i.e. by using a “mouse” for pointing and clicking.)

In the TolfaWeb, each resource has an attribute called “base price” (BP). It usually to the price in NOK for a member to book a room himself/herself for a single night (currently BP = 75).

The TBS has the following 8 different booking types built-in:

WName of booking typePrice (% rel)Price (NOK)By occupancyRGB colour
1MembersBPD × 10075TRUE88ffdd
2FamilyBPD × 133100TRUE88dd88
3Friends w. memberBPD × 267200TRUE99ffff
4Friends aloneBPD × 400300TRUE88eeff
5Friends, long term stayBPD × 200150TRUE5bcede
6WorkshopBPD × 867650FALSEffff00
7EventBPD × 00FALSEffaa00
8BlockedBPD × 00FALSEcccccc

In TolfaWeb, there are two global variable tolfa_baseprice_day (BPD, currently set to 75), and tolfa_baseprice_min (BPM, currently set to -1). All prices are computed by applying multipliers to this provided it is positive. A negative number means that it is not avilable.

In the table above, the column “Price (rel)” contains the multiplier (relative to base price) that is the price for that type of booking. The column “Price (NOK)” show the result of using the multiplier, and is the daily price for the booking in NOK. The column “By occupancy” is a flag (i.e. a true or false value) and defines whether price should be computed by occupancy (i.e. the number of adults and children that occupy the room), or by room (i.e. the price of a booking shall not depend on occupancy). The column “RGB colour” contains hexadecimal numbers corresponding to the colour used in visual presentations of the booking type.

Special price rules in Tolfa:

In TolfaWeb, a booking type instance is created dynamically by the RBG booking type class. It is simple to add, change and remove instances of this class.

In TolfaWeb each resource (i.e. an instance of RBG resource class) will have a base price associated with it, and the price for the actual booking is derived from a computation that takes into account the following:

  1. The daily base price for the resource instance.
  2. The booking type adjustment.
  3. If “By occupancy” is true, the price is adjusted according to occupancy (i.e. the number of adults and children that occupy the room).
  4. If the booking is in a period when there is a seasonal price adjustment, the price is adjusted accordingly.
  5. The duration (the number of days the resource is booked for).

The price of a booking is computed when a resource is booked. It is recomputed when the booking is edited (but the computation may still use the original base price). It is not automatically recomputed when the base price is changed. However, the booking master will be given the option to force a price change in upcoming (but unpaid) bookings, and a new invoice will be emailed to the person paying. Bookings that are marked as paid in full will not be recomputed by forcing a price change.

Price computation examples

Example 1: member with partner stays 10 days in a standard room in the standard season.

  1. The BPD is NOK 75.
  2. Computing resource price adjustment: NOK 75 × 100% = NOK 75
  3. Computing booking type adjustment for Members: NOK 75 × 1= NOK 75
  4. Computing occupancy: NOK 75 × 2 persons = NOK 150
  5. There is no seasonal price adjustment: NOK 150 × 1= NOK 150
  6. Computing duration: NOK 150 × 10 days = NOK 1500 (this is what this booking costs)

Example 2: Friend alone (1 person) stays 10 days in a standard room in the low season, and the low season adjustment is set to × 50%.

  1. The BPD is NOK 75.
  2. Computing resource price adjustment: NOK 75 × 100% = NOK 75
  3. Computing booking type adjustment for Friends alone: NOK 75 × 400% = NOK 300
  4. Computing occupancy: NOK 300 × 1 person × 100% = NOK 300
  5. Computing seasonal price adjustment: NOK 300 × 50% = NOK 150
  6. Computing duration: NOK 150 × 10 days = NOK 1500 (this is what this booking costs)

Example 3: member stays 10 days in T2.1 in the standard season.

  1. The BPD is NOK 75.
  2. Computing resource price adjustment: NOK 75 × 50% = NOK 37
  3. Computing booking type adjustment for Members: NOK 37 × 1= NOK 37
  4. Computing occupancy: NOK 37 × 1 person = NOK 37
  5. There is no seasonal price adjustment: NOK 37 × 1= NOK 37
  6. Computing duration: NOK 37 × 10 days = NOK 370 (this is what this booking costs)

Policies

In the TBS, the booking policy is in code only. This is very rigid and expensive to maintain. In TolfaWeb, policy will ultimately become an object that is part of the RBG category class (this means that it will be much simpler to create and maintain different booking policies for bedrooms, common rooms and the waiting list).

However, for TolfaWeb ver. 1, the policy is still in code, but exposed to the booking master through the GUI. Category constraints will be enforced through code, but the policy can be changed by the booking master through the GUI.

TolfaWeb shall reproduce the same policies as the TBS, but more flexible and more transparently.

Some policies are not even exposed through the GUI, as they are universal and should not be changed. For, now this applies to a the following:

Booking policy rules (X are suggested defaults (from the TBS), use X = -1 to disable a rule and other negative numbers for special purposes). Current state is in square brackets.

4. Classes and attributes

The core of TolfaWeb is based upon five classes (i.e. types of content). Four of those are inherited from RBG, while one in created for TolfaWeb (now by using the GUI, may become a features export). The description of each class consists of a list of attributes and a brief explanations of the attributes that are not self-explanatory or is explained elsewhere. A number in a square bracket connects the attribute to its explanation.

  1. RBG category: A caregory of resource, users may navigate between categories using tabs above the grid.
  2. RBG resource: A bookable resource.
  3. RBG booking type: The type of booking. Placeholder for additional attributes.
  4. RBG booking: An actual booking of a resource
  5. Tolfa season: A seasonal price adjustment

The data type or Drupal field is indicated insite parentheses for each attribute. The prefix “rel:” here means that the attribute is an entity relation to another class.

There is also a User class, and an Article class, that comes as part of Drupal and is inherited by TolfaWeb. Those are stadard features of the Drupal WCMS, and are not described here.

RBG category

TolfaWeb introduces a new level of abstraction above the actual resources (i.e. the rooms). This purpose of this class is to move the booking policy out of code and into an object that can be changed by the booking master through the GUI.

Inherited attributes:

TolfaWeb attributes:

Notes:

  1. The Category is used to name the category. The Tolfa service will initially define four categories named “Bedrooms”, “Common Rooms”, “Waiting list”, and “Meta”.
  2. Postponed to ver. 2.0.

RBG resource

This class is used to represent the bookable resource (e.g. a physical room or a pseudo-room).

Inherited attributes:

TolfaWeb attributes:

Notes:

  1. The Resource name is the name of the resource. In Tolfa the bedrooms are named V1-V8, T1, T2, T2.1, T3 and T4; the Common rooms are named SanG-salen and Ballsalen; and there are 7 pseudo-rooms on the waiting list: X1-X7.
  2. Like in TBS the base price (BP) is a global variable. This is the base price shared by all resources:
    • Each resource has two base prices, one for for daily and one for lower resolution rental (abbreviated BPD, BPM, -1 means NA, 0 means free). While Tolfa only rents by the day, this extra flexibily costs nothing.
    • However, the resource object instance may have a price adjustment set, given as an integer percentage. This allow for pricing some resources different from others (e.g. T2.1 is 75 × 50% = 37).
    • The base price in this object will only be used as a starting point for computing the cost of a booking. Refer to the examples above to learn how the price is computed.

RBG booking type

This class describes the various types of booking that are known to the system. The use of this class is described above in the section Prices.

Inherited attributes:

TolfaWeb attributes:

Notes:

  1. The booking type has a name. The names used in the TBS are listed in the table in the previous section. After creating these edit the $bt_classes array (located in rbg.controller.inc).
  2. The attribute By occupancy is a flag to indicate if price for this booking type should be computed by occupancy or not. In Tolfa, all bookings except workshops are by occupancy. Most commercial booking software does not even allow pricing by occupancy.
  3. The Percentage of base price is the percentage of the base price that will be used in the computation of the price of this booking type for the principal adult person in the room.
  4. The two Children attributes are used to compute the cost of having children in the room.
    • The Children 0-11 attribute is used to set the price of children under 12 years old sharing the room with at least one parent or grandparent. Setting it to 0 means that there is no cost to have the children sleeping in the same room as the parent(s).
    • The Children 12-17 attribute is used to set the price of children 12-17 years old traveling with member or family if they hace their own room.
  5. The three Quantum attributes are used to compute how the number of occupants in a room affects the price (and are not used if By occupancy is not set).
    • The Quantum absolute attribute is used to set the price when more adults than the Quantum modifier limit occupy the same room. Set to -1 to use Quantum modifier instead
    • The Quantum modifier attribute is used to compute the price when more adults than the Quantum modifier limit occupy the same room, and Quantum absolute is set to -1.
    • The Quantum modifier limit is used to indicate when to use the Quantum modifier. Setting it to 2 means that it used to compute the cost of the 3rd adult in the same room.

RBG booking

This is the actual booking. It has roughly the same attributes as the fields that appeared in the booking form in the TBS.

However, in TolfaWeb, bookings will have revisions enabled, so that we can extract historic booking patterns for analysis later. This is not possible in the TBS.

Inherited attributes:

TolfaWeb attributes:

Notes:

  1. The Owner is always the member who the booking is made for (either by self-service booking, or by the booking master on behalf of a member). In TolfaWeb, it is the owner of the booking node. A member can create, edit and delete own booking instances (according to the booking policy). The booking master can do the same thing to all booking instances, and is not constrained by the booking policy.
  2. The booking state feature is not used in Tolfa (all booking will be automatically set to Confirmed as soon as they are created), but it should be in place in TolfaWeb in case we want to enable a booking policy that allows bookings to be disputed.
  3. This should only be visible when the booking type indicate that the booking is not for the Member.
  4. For most booking types, the service needs to know the number of Adults and Children aged 0-11 and Children aged 12-17 in order to compute the price for the booking based upon the Tolfa price model. However, this information will no longer be requested on the booking form if the booking type has the “By occupancy” flag set to false.
  5. We also retain the actual Base price used when the booking was made, so that if the base price for the resource is changed, but the booking master choses not to force this change on bookings that are already confirmed and an invoice has been sent out, editing the booking will not automatically result in a different price. For legacy bookings, this is set to the base price at the time TolfaWeb is deployed.
  6. This is usually a computed price based upon the price model, but may be overridden by the booking master. If it is overridden, it is indicated by the Booking locked flag.
  7. If the Booking locked flag is set, the booking cannot be changed by the owner, even if the rules otherwise would permit this. This is automatically set when a special price is set by the booking master. In TBS this field was named “spfymf” (special price for you my friend).
  8. The Legacy user ID retains the user ID from the TBS. This is to make sure we are able to reconnect users to bookings when we migrate the legacy user and booking data into TolfaWeb.

Tolfa season

This class is to enable seasonal price adjustments (e.g. “low season” pricing for November - February).

The booking master can create any number of price adjustment instances in the GUI, and each instance can apply to a single resource or to all resources. They cannot overlap.

TolfaWeb attributes:

Untick “Promoted to front page” and set comments “Closed”.

Notes:

  1. The Period records the period when price adjustment apply (i.e. the beginning date and the end date).
  2. The Campaign flag indicates whether the price adjustment is of the type “Recurring” (default) or “Campaign”. A Campaign adjustment, when set, is automatically deactivated when it expires. A Recurring adjustment, will be automatically reactivated annually as long as it is not deleted. Recurring adjustments are for setting up “low season” discounts. Campaigns are for running time-limited promotions. Tick “Use field label instead of the "On value" as label” TODO: Improve display.
  3. The price adjustment may apply to a single resource, or to - All - resources. The latter is a meta-resource that appears on the pull-down menu.
  4. The Percentage is the discount (expressed as a percentage) that is applied to the price computation of a resource as the penultimate step in computing the cost of a stay (just before duration is applied). It is used in step 5 in this example.

6. Roadmap

Optional features

Optional features are not enabled by default, but may be enabled by the booking master.

  1. When a resource is booked, email is sent to all members who subscribe to notices about booking of this resource.
  2. X days before arrival, an email is sent to all members who subscribe to notices about booking gets a reminder/invoice by email (X = 40).
  3. Feature to export to Excel for client side analysis.
  4. The initial booking state can be set to pending, and other members may then dispute the booking (i.e. indicating that they also want to use the resource at the same time). If there are no disputes in X days, the booking is automatically confirmed. This is not used in Tolfa, but having it in place will allow for more flexible booking policies than the present: “the first to book gets the room”.

Wishlist

The wishlist lists ideas that would be nice to have, but that will not be included in the first release.

  1. Shopping cart: Ability to book more than one room in a linked context, producing a single invoice for all rooms booked in this context.
    See: ostraining.com/blog/drupal/basic-cart/.
  2. Limit abusive bookings: Add a policy to limit abusive bookings (see separate design document).
  3. It would be nice to reveal the last slot avilable in the departure tooltip.

Sociability extensions

This section is for description of features that may increase the sociability of the service.

  1. Users are encouraged to enter they year and date of their birthday as part of their user profile. This will allow:
    • Ability to compute the age demographic of the users (the board is interested in this).
    • Birthday greeting: Members who log in on their birthday receive a "happy birthday" message.
    • A birthday Resource in the External-category (see below). It will indicate the date, but not the year. Users may opt out if they do not want to share their birthday with other users.
  2. An External category. In this category, the individual resources are birthdays, cultural events ("culture calendar"), local festivals, Italian holidays. etc. etc.

7. Deployment

Install the following custom projects and dependencies:

  1. RBG
  2. Tolfa
  3. Flexilogin
  4. Mother May I

Setting up

To set up a production booking service for the Tolfa website, do the following to create the Tolfa season class and the required instances:

  1. Create Tolfa season using the GUI.
  2. Create three RBG categories: Bedrooms, Common rooms, Waiting list
  3. Create the RBG resources: V1-V8, T1, T2, T2.1, T3, T4 (Bedrooms); SanG-salen, Ballsalen (Common rooms); X1-X7 (waiting list); - Alle - (meta).
  4. Create RBG booking types equivalent to the TBS (these are described above).
  5. To offer a discount for the low season, create a Tolfa season from 2018-11-01 to 2019-03-01.

At this point, the site should be very similar to the legacy TBS. It may be a good idea to create a backup.

  1. Add a phonefield to user profile, make it mandatory.
  2. Create the role “booking master”.
    • Give the booking master role the following permission: Adminster RBG, as well as all node permissions for the RBG content types and the Tolfa season content type.
    • Give all authenticated users the following node permissions: RBG booking: Create new content, Edit own content, Delete own content.
  3. Create test users “test” and “bm” and give the latter the booking master role.

The suggested access control will give the booking master full access to a GUI that allow him/her to create, change and remove instances of all classes.

Ordinary users will only have GUI access to the Booking class.

Configuration

[TBA]

Known bugs

  1. Editing a resource reverts category back to first category.

Migrate legacy data

At this point, it is possible to import legacy data from the TBS into TolfaWeb.

Insert credentials for legacy database in settings.php.

Manual tests

8. Final comments

[TBA]

Last update: 2018-08-19.