Comment on page

Bookings

Access this System's Event data, via the Calendar Driver

Type: Logic Driver
Dependencies: PlaceOS Calendar Driver
Source: https://github.com/PlaceOS/drivers/blob/master/drivers/place/bookings.cr
Functions
Fetches a room's Events and exposes them along with the current state of the room's calendar.
Provides check-in, auto cancel and decline functions.
Provides status for Booking panel app, kiosk and workplace app (explore/map page) for live room availability data
Common Configurations
Basic Free / Busy
Settings for basic free busy status, where the room indicates a pending meeting 5minutes before a meeting starts.
pending_before: 5 # pending 5min before a meeting start
pending_period: 0 # show the room as busy as soon as it starts
disable_end_meeting: true
Manual Check-in
The Booking panel app will end the meeting early if no one checks in manually.
pending_before: 5 # pending 5min before a meeting start
pending_period: 10 # end the meeting after 10min if no check-in
The booking panel itself performs the meeting end, this prevents meetings from being ended if the panel is offline.
Sensor Based Check-in
Utilises a sensor to check-in the meeting (requires the 'Check-In Helper' module in the system)
pending_before: 5 # pending 5min before a meeting start
disable_end_meeting: true # disable panel from ending the meeting
​
# look for people 5min into the meeting
present_from: 5 # in case the previous meeting went over time
prompt_after: 10 # auto-cancel at 10minutes
auto_cancel: true # enable auto-cancel (can alternatively email the user)
Settings
Key
Type
Default value
Description
calendar_id
String
nil
The email address of the room the module is in
calendar_time_zone
String
Australia/Sydney
Currently has no impact
book_now_default_title
String
Ad Hoc booking
Title of booking if unchanged
disable_book_now
Boolean
false
​
disable_end_meeting
Boolean
false
Exposes a disable_end_meeting status variable such that frontends like PlaceOS template Bookings can detect it and enable/disable it's auto event cancellation functionality (frontend will exec end_meeting causing the current event to be truncated to the current time, freeing up the room (in case of no shows).
pending_period
UInt32
5
Number of minutes AFTER the Booking start time until status changes from pending to free
pending_before
UInt32
5
Number of minutes BEFORE the Booking start time until the status changes from free to pending
cache_polling_period
UInt32
5
​
cache_days
UInt32
30
​
sensor_stale_minutes
Int32
8
Consider sensor data older than this unreliable
change_event_sync_delay
UInt32
5
As graph API is eventually consistent we want to delay syncing for a moment
control_ui
String
https://if.panel/to_be_used_for_control
​
catering_ui
String
https://if.panel/to_be_used_for_catering
​
include_cancelled_bookings
Boolean
false
​
hide_qr_code
Boolean
false
​
custom_qr_url
String
https://domain.com/path
​
custom_qr_color
String
black
The colour of the QR codes the module generates
room_image
String
https://domain.com/room_image.svg
This image is displayed along with the capacity when the room is not bookable
sensor_mac
String
device-mac
​
hide_meeting_details
Boolean
false
​
hide_meeting_title
Boolean
false
​
Status Variables
bookable
true if the room can be directly booked by end users without going through an admin
Schema/Type
Boolean
room_name
The name of the room
Schema/Type
String
room_capacity
Max number of people that can be booked into a meeting in the room
Schema/Type
Int
default_title
Title of meetings if none is set
Schema/Type
String
disable_book_now
Schema/Type
Boolean
disable_end_meeting
Exposes a disable_end_meeting status variable such that frontends like PlaceOS template Bookings can detect it and enable/disable it's auto event cancellation functionality (frontend will exec end_meeting causing the current event to be truncated to the current time, freeing up the room (in case of no shows).
Schema/Type
Boolean
pending_period
Number of minutes AFTER the Booking start time until status changes from pending to free
Schema/Type
UInt32
pending_before
Number of minutes BEFORE the Booking start time until the status changes from free to pending
Schema/Type
UInt32
control_ui
Schema/Type
String
catering_ui
Schema/Type
String
show_qr_code
Schema/Type
Boolean
connected
Schema/Type
Boolean
booked
true when there is a current (start time < current time < end time)
Schema/Type
Boolean
current_pending
true from the event start time until pending_period mins after the event start time OR until checkin / start_meeting is executed.
Schema/Type#
Boolean
next_pending
true from pending_before mins before an event start time until the event start time OR until checkin / start_meeting is executed.
Schema/Type
Boolean
pending
true when either current_pending or next_pending is true
Schema/Type
Boolean
in_use
true when booked AND NOT pending (means that the current event has been checked in via checkin OR start_meeting functions)
Schema/Type
Boolean
status
Describes the current status of the room
Schema/Type
free, pending, busy
bookings
Contains an array of Events that occur in this System's mailbox (see system.email property) between the start of the current day (in the timezone of the core service) and the cache_days setting.
Schema/Type
See also: https://github.com/PlaceOS/calendar/blob/master/src/models/event.cr
[
    # todo: move the Event schema to a single dedicated page, that other pages will link to.
    {
        event_start: Integer # Linux Epoch
        id: String
    }
]
Examples
1. No events
[]
Commands
calendar_id
Displays the calendar ID - This means the ID of the room, which is the email address assigned to the room in BackOffice, as each room has its own calendar.
Parameters
Name
Required?
Type
Default
Description
None
​
​
​
​
Response Schema
​
Example Responses
1. If successful:
[email protected]
start_meeting
Starts a booked current or future meeting in the current room, to prevent automatic cancellation.
Parameters
Name
Required?
Type
Default
Description
meeting_start_time
true
Int64
Nil
The time of the meeting you wish to start, in Unix time
Response Schema
​
Example Responses
1. If successful:
null
checkin
Starts the current meeting in the current room to prevent automatic cancellation.
Parameters
Name
Required?
Type
Default
Description
None
​
​
​
​
Response Schema
​
Example Responses
1. If successful:
null
end_meeting
Ends the meeting in the current room which has the start time entered.
Parameters
Name
Required?
Type
Default
Description
meeting_start_time
true
Int64
N/A
The start time of the meeting the user wishes to cancel in seconds (Unix time)
notify
false
Boolean
false
If set to true, this will notify the other meeting participants
comment
false
String
nil
This will be added to the notification
Response Schema
​
Example Responses
1.
​
book_now
Books and starts a meeting in the current system which starts immediately and lasts an certain length of time in seconds as specified by the user.
Parameters
Name
Required?
Type
Default
Description
period_in_seconds
true
Int64
N/A
The length of the meeting the user is booking in seconds
title
false
String
nil
The name of the meeting
owner
false
String
nil
The email of the host of the meeting as registered in BackOffice. Does not work if this is filled in with a host that does not exist. Works if left empty.
Response Schema
​
Example Responses
1. If the owner does not exist:
{
    "error": "request failed",
    "sys_id": "sys-EJeSmse5Z2",
    "module_name": "Bookings",
    "index": 1,
    "message": "module raised: remote exception: Bad Request (PlaceCalendar::Exception) (PlaceOS::Driver::RemoteException) (PlaceOS::Driver::RemoteException)",
    "backtrace": [
        "repositories/drivers/lib/place_calendar/src/office365.cr:420:7 in 'handle_office365_exception'",
        "repositories/drivers/lib/place_calendar/src/office365.cr:213:7 in 'create_event'",
        "repositories/drivers/lib/place_calendar/src/place_calendar.cr:23:5 in 'create_event'",
        "repositories/drivers/drivers/place/calendar_common.cr:322:14 in 'create_event'",
        "repositories/drivers/drivers/microsoft/graph_api.cr:3:1 in '->'",
        "repositories/drivers/drivers/microsoft/graph_api.cr:3:1 in 'execute'",
        "repositories/drivers/lib/placeos-driver/src/placeos-driver/driver_manager.cr:164:5 in 'execute'",
        "repositories/drivers/lib/placeos-driver/src/placeos-driver.cr:522:1 in 'run_execute'",
        "repositories/drivers/lib/placeos-driver/src/placeos-driver/driver_manager.cr:262:24 in 'process'",
        "repositories/drivers/lib/placeos-driver/src/placeos-driver/driver_manager.cr:179:7 in '->'",
        "/usr/share/crystal/src/fiber.cr:146:11 in 'run'",
        "/usr/share/crystal/src/fiber.cr:98:34 in '->'",
        "???"
    ]
}
2. If neither optional field is filled out:
{
    "event_start": 1678359840,
    "event_end": 1678361880,
    "id": "AAkALgAAAAAAHYQDEapmEEGaBh1ZdOKM9wAEWahNjgAA",
    "host": "[email protected]",
    "title": "Test",
    "body": "",
    "attendees": [
        {
            "name": "Resource - Meeting Room  ",
            "email": "[email protected]",
            "response_status": "accepted",
            "resource": true
        }
    ],
    "location": "Australia/Sydney",
    "private": false,
    "all_day": false,
    "timezone": "Etc/GMT",
    "recurring": false,
    "created": "2023-03-09T11:04:48Z",
    "updated": "2023-03-09T11:04:48Z",
    "attachments": [],
    "status": "confirmed",
    "creator": "[email protected]",
    "ical_uid": "04000000820008000000000E15B0F67652D901000000000000000182B5434CB8A1190D33B69031",
    "online_meeting_provider": "unknown",
    "online_meeting_phones": []
}
3. If the room is already booked:
{
    "event_start": 1677862320,
    "event_end": 1677868320,
    "id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0XoQbkCdlH4poLQWvwAApKCC7wAA",
    "host": "[email protected]",
    "title": "Ad Hoc booking",
    "body": "",
    "attendees": [
        {
            "name": "Test Room 3",
            "email": "[email protected]",
            "response_status": "accepted",
            "resource": true
        }
    ],
    "location": "Australia/Sydney",
    "private": false,
    "all_day": false,
    "timezone": "Etc/GMT",
    "recurring": false,
    "created": "2023-03-03T16:52:09Z",
    "updated": "2023-03-03T16:52:09Z",
    "attachments": [],
    "status": "confirmed",
    "creator": "[email protected]",
    "ical_uid": "040000008200E00074C5B7101A82E0080000000071000000000000000010000000088E69420B979D46A74BB28B9BFEFBAD",
    "online_meeting_provider": "unknown",
    "online_meeting_phones": []
}
poll_events
Query neighbouring calendar driver for Events that occur in this System's mailbox (see system.email property) between the start of the current day (in the timezone of the core service) and the cache_days setting. Updates the state with this information, rather than returning it as a response.
Parameters
Name
Required?
Type
Default
Description
None
​
​
​
​
Response Schema
​
Example Responses
1. If successful:
[]
locate_user
Used by location services and area management drivers to locate a given user within the building. Not useful as a command on its own, only used by the location drivers. Nothing to do with the specific system the module is in, the location services use this command to poll each room for a specific user. If they are not present in the current room, it returns an empty array. Neither the username or email is required but at least one should be used for the command to be useful. The username is often the same as the username but in some cases is not, which is why there are two fields.
Parameters
Name
Required?
Type
Default
Description
email
false
String
nil
The email of the user to search for
username
false
String
nil
If no username matches, it will search for emails that begin with the username
Response Schema
​
Example Responses
1. If user is not in the room OR the user AND email do not exist:
[]
macs_assigned_to
Uses locate_user to find the MAC addresses assigned to users matching the email and username. Neither the username or email is required but at least one should be used for the command to be useful. Used by the location services and area management drivers and is not useful on its own.
Parameters
Name
Required?
Type
Default
Description
email
false
String
nil
Searches for the MAC address of the user with email entered
username
false
String
nil
Searches for the MAC address of the user with username entered. Will search for emails that begin with the username if none are found
Response Schema
​
Example Responses
1. If user is not in the room OR does not exist:
[]
check_ownership_of
Searches for a user by their MAC address. It will show the user the MAC address is assigned to as well as the meeting they are in. Used by location services and area management drivers and is not useful on its own.
Parameters
Name
Required?
Type
Default
Description
mac_address
true
String
N/A
The MAC address to search for
Response Schema
​
Example Responses
1. If the MAC address belongs to a user:
    {
        location:    "meeting",
        assigned_to: host,
        mac_address: sys_email,
      }
2.
[]
device_locations
Searches for all devices in a specific zone by zone ID or location name. Used by location services and area management drivers, not useful on its own.
Parameters
Name
Required?
Type
Default
Description
zone_id
true
String
N/A
Zone ID of device search
location
false
String
nil
name of location
Response Schema
​
Example Responses
1.
[]
is_stale?
Checks if the information it has from room sensor data is old or up-to-date. Returns true if the information is old. Used by location services and area management drivers, not useful on its own.
Parameters
Name
Required?
Type
Default
Description
timestamp
true
Boolean
N/A
The timestamp it receives from the location drivers to check if its info is old or not - Unix time
Response Schema
​
Example Responses
1.
true
2.
null

Key	Type	Default value	Description
`calendar_id`	String	nil	The email address of the room the module is in
`calendar_time_zone`	String	Australia/Sydney	Currently has no impact
`book_now_default_title`	String	Ad Hoc booking	Title of booking if unchanged
`disable_book_now`	Boolean	false
`disable_end_meeting`	Boolean	false	Exposes a disable_end_meeting status variable such that frontends like PlaceOS template Bookings can detect it and enable/disable it's auto event cancellation functionality (frontend will exec end_meeting causing the current event to be truncated to the current time, freeing up the room (in case of no shows).
`pending_period`	UInt32	5	Number of minutes AFTER the Booking start time until status changes from pending to free
`pending_before`	UInt32	5	Number of minutes BEFORE the Booking start time until the status changes from free to pending
`cache_polling_period`	UInt32	5
`cache_days`	UInt32	30
`sensor_stale_minutes`	Int32	8	Consider sensor data older than this unreliable
`change_event_sync_delay`	UInt32	5	As graph API is eventually consistent we want to delay syncing for a moment
`control_ui`	String	https://if.panel/to_be_used_for_control
`catering_ui`	String	https://if.panel/to_be_used_for_catering
`include_cancelled_bookings`	Boolean	false
`hide_qr_code`	Boolean	false
`custom_qr_url`	String	https://domain.com/path
`custom_qr_color`	String	black	The colour of the QR codes the module generates
`room_image`	String	https://domain.com/room_image.svg	This image is displayed along with the capacity when the room is not bookable
`sensor_mac`	String	device-mac
`hide_meeting_details`	Boolean	false
`hide_meeting_title`	Boolean	false

Name	Required?	Type	Default	Description
None

Name	Required?	Type	Default	Description
meeting_start_time	true	Int64	Nil	The time of the meeting you wish to start, in Unix time

Name	Required?	Type	Default	Description
None

Name	Required?	Type	Default	Description
meeting_start_time	true	Int64	N/A	The start time of the meeting the user wishes to cancel in seconds (Unix time)
notify	false	Boolean	false	If set to true, this will notify the other meeting participants
comment	false	String	nil	This will be added to the notification

Name	Required?	Type	Default	Description
period_in_seconds	true	Int64	N/A	The length of the meeting the user is booking in seconds
title	false	String	nil	The name of the meeting
owner	false	String	nil	The email of the host of the meeting as registered in BackOffice. Does not work if this is filled in with a host that does not exist. Works if left empty.

Name	Required?	Type	Default	Description
None

Name	Required?	Type	Default	Description
email	false	String	nil	The email of the user to search for
username	false	String	nil	If no username matches, it will search for emails that begin with the username

Name	Required?	Type	Default	Description
email	false	String	nil	Searches for the MAC address of the user with email entered
username	false	String	nil	Searches for the MAC address of the user with username entered. Will search for emails that begin with the username if none are found

Name	Required?	Type	Default	Description
mac_address	true	String	N/A	The MAC address to search for

Name	Required?	Type	Default	Description
zone_id	true	String	N/A	Zone ID of device search
location	false	String	nil	name of location

Name	Required?	Type	Default	Description
timestamp	true	Boolean	N/A	The timestamp it receives from the location drivers to check if its info is old or not - Unix time

PlaceOS

Staff API

Last modified 3mo ago