Bookings

Kate Santo Updated by Kate Santo

Bookings are posts of type event that allow users to reserve themselves a slot. This slot might be for things like: a meeting room in a workplace app; a parking space or a shared space in a property app; a sports pitch in a community engagement app; etc.

Find out more about bookings in this guide.

See for yourself

  • You can download the iOS or Android app on your phone to follow this journey along. And you can also log in or sign up to the web app here
  • You can also follow along by checking out the images or code snippets in this guide
  • And you will find the relevant endpoints linked and explained in this guide, but the full API is documented in Swagger UI

Prerequisites

  • For bookings to display in the UI, the padoq needs its official and qrEnabled parameters setting to true. This can only be done by an admin as padoqs don't default to these settings

Bookings

Bookings are event posts with specific bits of data attached. In broad terms, an event is a post with structured content that includes information like amount (if the event is paid), frequency (if the event is recurrent) or maxAttendees (to limit how many people can attend the event). A booking will have properties like amount and frequency, but also properties like isAppointment (which has a value of true, differentiating a booking from a standard event).

There's a property in a member's profile that interacts with bookings: bookingLimit which defines how many hours the member can book rooms (or any other entities) for. It looks like this:

{
"bookingLimit": 1750
}

And, in the padoq, the bookingInfo property defines the size of the bookable time slots:

"bookingInfo": {
"bookingRestrictions": {
"slot": {
"units": "HOURS",
"maxDuration": 1,
"minDuration": 1
},
"quantity": [
{
"period": 24,
"allowance": 3,
"periodUnits": "HOURS",
"allowanceUnit": "HOURS"
},
{
"period": 28,
"allowance": 12,
"periodUnits": "DAYS",
"allowanceUnit": "HOURS"
}
]
}
}

In that example, members can book a maximum of 3 hours in any 24 hour period, and 12 hours in any 28 day period. In property apps, for example, this ensures all tenants have fair access to bookable rooms and services, because not one tenant can book a room for excessive periods of time.

Each bookable room or space is set up as a calendar user. This ensures that the same room can't be booked twice at the same time.

Creating bookings

One of the key properties in a padoq is permittedPostTypes, which sets the types of posts members can create. Events, like bookings, are not permitted as default. The padoq admin needs to add events to the list of permittedPostTypes to allow members to create bookings.

The process to create a booking is the same as the process to create a post. The user needs to be authenticated in the app, and the app needs to allow members to create posts overall and events in particular.

Then, the createPost endpoint is called. It takes 2 parameters: name of the padoq to create the post in and role, which optionally sets the user's role. The data sent through the UI (either by a member if the padoq allows it or by an admin in the Super Admin page) will generate a booking that might look like this when viewed through the browser:

BEGIN:VEVENT
UID:12345678-abcd-ab12-ab12-12345abcde
DTSTAMP;TZID=Europe/London:20200709T215317
DTSTART:20200709T220000Z
DTEND:20200709T230000Z
SUMMARY:MeetingRoomS1
DESCRIPTION:MeetingRoomS1 booked by JaneSmith
STATUS:CONFIRMED
ORGANIZER;CN=My_Padoq:CAL-ADDRESS:https://app.padoq.com/resrc/padoq/My_Padoq/persona/My_Padoq
ATTENDEE;PARTSTAT=ACCEPTED;CN=MeetingRoomS1:CAL-ADDRESS:https://app.padoq.c
om/resrc/padoq/My_Padoq/persona/MeetingRoomS1
ATTENDEE;PARTSTAT=NEEDS-ACTION;CN=user1:CAL-ADDRESS:https://app.padoq.com/re
src/padoq/My_Padoq/persona/user1
URL:https://app.padoq.com/resrc/padoq/My_Padoq/post/12345678-abcd-ab12-ab12-12345abcde/version/1
END:VEVENT

Reading bookings

Bookings are displayed via the getPosts endpoint with some parameters:

  • name of the padoq we are getting posts for
  • Accept: the type of response the endpoint accepts. In this case, it's data of type text/calendar, as opposed to the JSON format most endpoints take
  • postStatus (optional): this allows to only view bookings that are open or cancelled

Updating and deleting bookings

Updating and deleting bookings is done via the editPost and deletePost endpoints. In the Super Admin page, bookings are deleted via this option in the UI (see 'cancel booking' button on the bottom-right corner):

On mobile, members can edit and cancel their bookings (referred to as 'events' here) via an overlay menu:

Beyond editing and deleting, admins can limit how many times a padoq member can make bookings. This is done via the updatePersonaBookingLimit. A booking limit of 0, for example, means that the user can't make bookings in that padoq:

{
"bookingLimit": 0
}

A booking limit of 1750, for example means that the user can book a maximum of 1750 hours in that padoq:

{
"bookingLimit": 1750
}

How did we do?

Create and Manage Forms (Information Collection)

Privileges

Contact