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
- 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
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
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.
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)
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 | |
true if the room can be directly booked by end users without going through an admin
Boolean
The name of the room
String
Max number of people that can be booked into a meeting in the room
Int
Title of meetings if none is set
String
Boolean
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).
Boolean
Number of minutes AFTER the Booking start time until status changes from pending to free
UInt32
Number of minutes BEFORE the Booking start time until the status changes from free to pending
UInt32
String
String
Boolean
Boolean
true when there is a current (start time < current time < end time)
Boolean
true from the event start time until pending_period mins after the event start time OR until checkin / start_meeting is executed.
Boolean
true from pending_before mins before an event start time until the event start time OR until checkin / start_meeting is executed.
Boolean
true when either current_pending or next_pending is true
Boolean
true when booked AND NOT pending (means that the current event has been checked in via checkin OR start_meeting functions)
Boolean
Describes the current status of the room
free, pending, busy
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.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
}
]
1. No events
[]
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.
Name | Required? | Type | Default | Description |
---|---|---|---|---|
None | | | | |
1. If successful:
Starts a booked current or future meeting in the current room, to prevent automatic cancellation.
Name | Required? | Type | Default | Description |
---|---|---|---|---|
meeting_start_time | true | Int64 | Nil | The time of the meeting you wish to start, in Unix time |
1. If successful:
null
Starts the current meeting in the current room to prevent automatic cancellation.
Name | Required? | Type | Default | Description |
---|---|---|---|---|
None | | | | |
1. If successful:
null
Ends the meeting in the current room which has the start time entered.
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 |
1.
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.
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. |
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": []
}
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.Name | Required? | Type | Default | Description |
---|---|---|---|---|
None | | | | |
1. If successful:
[]
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.
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 |
1. If user is not in the room OR the user AND email do not exist:
[]
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.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 |
1. If user is not in the room OR does not exist:
[]
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.
Name | Required? | Type | Default | Description |
---|---|---|---|---|
mac_address | true | String | N/A | The MAC address to search for |
1. If the MAC address belongs to a user:
{
location: "meeting",
assigned_to: host,
mac_address: sys_email,
}
2.
[]
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.
Name | Required? | Type | Default | Description |
---|---|---|---|---|
zone_id | true | String | N/A | Zone ID of device search |
location | false | String | nil | name of location |
1.
[]
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.
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 |
1.
true
2.
null
Last modified 3mo ago