Bookings API / Public Bookings

Events happening in the community are now at Drupal community events on www.drupal.org.
You are viewing a wiki page. You are welcome to join the group and then edit it. Be bold!
Posted by Anonymous on November 10, 2009 at 9:52am
Last updated by Anonymous on Thu, 2010-01-07 16:27

Hi,

this is just a short documentation and roadmap for the Bookings API and Public Bookings modules.

At the moment Bookings API (6.x-1.0) is using an own, custom resource-type. Using nodes is not possible at the moment (I am writing on a new version which will use a node-based resource-type (6.x-3.0) but so far it is NOT usable). Thus it's not needed to add a custom node-type.
In the future Bookings API will add its own node-type for resources. In an even farer future, I will allow using your own custom node-type - but let me first get the easy stuff set up ;)

Steps to use Public Bookings and Bookings API

  1. Install Bookings API and Public Bookings and their prerequisites
  2. Go to admin/content/publicbookings/settings and activate the Booking form. Perhaps you like to check some other settings too? You can e.g. set the granulation of bookings, whether a confirmation of email-addresses is needed or whether an administrator needs to finalize (check) each booking.
  3. Add Resources on admin/content/publicbookings/resource - there you can set whether a resource can be booked, if its available, etc
  4. Use it ;) - Public Bookings has a public interface (/publicbookings) and an administrative interface ( /admin/content/publicbookings/ ). Have a look at both of them (resources can be added in a sub-menu of the administrative interface)

Resources

Each resource has to have a title and a default availability. It may have additional information (e.g. Location) or a set of additional availabilities (ether repeating or single events, e.g. for service). Resources can be found and configured at admin/content/publicbookings/resource

  • Strictly unavailable won't be bookable whatever you do
  • Unavailable wont be bookable, but you can add additional availabilities (e.g. available each day from 10-12)
  • Available will be bookable, unless you add additional unavailabilities
  • Strictly available will be bookable, whatever you do

Bookings

An administrator (admin/content/publicbookings) may add bookings with repeats and a pre-defined state (e.g. finalized). An user (/publicbookings) may add bookings - but w/o repeats. In the default settings each bookings has to be agreed on by an administrator (e.g. set to finalized or canceled), other settings like automatically finalizing a booking can be set on the settings page.

States of a bookings:

  • Unconfirmed - Anonymous booking. The client has yet to confirm his Email-address
  • Pending - The client has confirmed his Email-address, but no administrator has confirmed the booking
  • Finalized - The booking is confirmed and conflicts with new bookings
  • Canceled - Either administrator or client have canceled the booking

A client will receive an Email with a confirmation key. This confirmation key can also be used as a passphrase to change the booking (e.g. cancel it or add additional information). An administrator will have a single page showing all upcoming bookings.

Views can be constructed (a set of pre-defined views exists) to show bookings, resources or availabilities.

Booking-flow

  • A client opens the bookings page at publicbookings/request/add, selects a resource and enters some information (e.g. start and end date, name, email, ..).
  • If the booking does not conflict with any existing booking, it will be entered with a state of "unconfirmed" - otherwise it will be rejected.
  • The client will receive a confirmation email with a link and a passphrase - on confirmation of his email address the booking will be set to "pending".
  • An administrator reviews the booking and decides whether to cancel or to finalize it - the client will be informed accordingly

Trigger and Rules

Any step in the booking process (e.g. adding a new booking, changing a booking, changing a resource, etc) can trigger an action - two submodules (Bookings API Trigger and Bookings API Rules) can be used together with Action / Trigger to react to them (e.g. inform the administrator of each new booking).

Bookings API 3.x

Bookings API is in work. It will see a large number of changes. Among others:

  • The custom data-type of the 1.x API version will be replaced with a node-based version (resources as nodes, bookings as nodes, etc)
  • The hooksystem of the module will be completely remodeled - allowing a large number of changes in additional modules
  • Resources will see a number of changes - Resource-relations will get recursive, only two default availabilities will be kept, etc
  • An additional database-table is added - it contains a list of *free* time slots and is calculated on-the-fly (and of course it can be recalculated). This makes it easy to e.g. list a set of available resources.
  • As resources are nodes they can contain additional information like Taxonomy data.

What is a resource relation

A resource may have a parent-resource. Those relations are recursive (parent-resource, grand-parent-resource, etc).
Parent/child nodes share bookings and availabilities, but not their default availability (if a child resource is booked the parent resource is unavailable too, if a parent-resource is booked all child-nodes are unavailable, etc). This allows grouping of resources. Disabling a resource does not disable its child/parent resources.

Example

Imagine a set of marbles containing of three bags, each containing several dozen marbles.

  • The whole set is a resource with disabled bookings (no one books the whole set!), a default availability of unavailable and a set of availabilities each day (except Monday) from 10:00 to 16:00 (no playing with marbles in the afternoon!)
  • A bag is a resource with the set as parent-resource. It can be booked (booking whole bags is possible, maybe you want to give a marble-party?). Bag three has an unavailability Sundays from 10:00 till 26:00 - so its only available from Tuesday till Saturday (actually, the owner wants to play himself).
  • A marble is a resource with a bag as parent-resource. Via taxonomy you could e.g. build a list of blue or sparkling marbles.

As a result all marbles in Bag 1&2 can be booked each day (except Monday) from 10:00 till 16:00 and in Bag 3 only from Tuesday till Saturday. A whole bag can be booked as long as no marbles in the bag are booked, and a marble can be booked as long as neither the marble nor its bag are booked.
Cool, isn't it?

API

Please be aware that API 3.x is under heavy development - it IS changing. In addition I'm working on the API documentation.

Minimal list of Hooks in Bookings API 3.x

All Hooks and functions without leading bookingsapi_

Hook Function OP Data Config Time of calling Special
booking recalculate_free_cache conflict $booking If a conflict with an existing booking was found during cache-rebuild
booking record_delete delete record_id Prior to deleting record and all instances via SQL
booking availability_save insert/update $availability Prior to saving
booking booking_save insert/update $booking After loading and status change, prior to saving
booking booking_list list
  • resource_id
  • booking_type
  • status
  • start
  • end
  • rev_start_end
    		 After building the list and prior to returning it
    conflict_check conflict_check check $record
    • new = BOOLEAN whether its new
    • conflictChange = BOOLEAN whether a change between conflict<->no-conflicting occured
    • timeChange = BOOLEAN whether the time changed
    • conflictArray &= Array of conflicts to fill
    • status &= conflict-status BOOKINGSAPI_CONFLICTS_NO, etc
    • abortAfter = BOOLEAN whether to abort conflict checking after all hooks were called
    • intervals &= Array of booking-intervals
    • exceptions &= Array of interval-exceptions
    		 Prior to running the build-in conflict checking
    free_cache recalculate_free_cache delete
    • resource_id = resource_id
    		 Prior to deleting the cache
    free_cache recalculate_free_cache insert
    • resource_id=resource_id
    • availabilities=list of availabilities
    		 Prior to inserting the availabilities into the database
    record_status record_status_change change $record
    • status=new status
    		 After Loading, prior to saving
    resource resource_delete delete resource Prior to deleting records and resource
    resource resource_save insert/update $resource (node) After initialization, prior to saving
    resource resource_get_childs list Existing list
    • type = minimal
    • parent=id
    		 Prior to return
    resource resource_list list Array or resource-ids found
    • type=full
    • element
    • limit
    • sort
    		 After builind list of ids, prior to calling resource_mass_load
    resource resource_minimal_list list Existing list
    • type=minimal
    		 After initial query, prior to return
    resource resource_load load $resource (node)
    • cached=TRUE
    		 After initialization, prior to return [1]
    resource resource_mass_load load Array of resources or single resource
    • cached=FALSE
    		 After initial loads, prior to return [1]
    timeframe timeframe_survey survey SQL-Statement selected columns Prior to db_query
    • Will be rewritten / removed / changed
      [1] Set $resource->FORCE_TYPE_OVERRIDE if the resource is not of the default type BOOKINGSAPI_RESOURCE_TYPE and should be includes nevertheless

    RoadMap

    Please see this issue

    Booking Systems

    Group organizers

    Group notifications

    This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

    Hot content this week

    See all hot content.