Room Booking

This application allows you to

1. create an event in a room booking calendar via a REST API.
2. delete an event in a room booking calendar via a REST API.
3. clear colliding and canceled events in a room booking calendar via script.

Setup

If you see this page, the application is already running.

You will have to create users, API keys and calendars via admin interface.

Usage

A full documentation of the API is available at /api/docs/.

Authentication is done via a Bearer token in the Authorization header.

Create an event

To create an event, you need to send a POST request to /api/{calendar}/events/ with the following JSON payload:

{
  "name": "Event Title",
  "start": "2025-01-02T12:00:00",
  "end": "2025-01-02T13:00:00"
}

Curl example:

 curl -s \
   -H "Authorization: Bearer secrettoken" \
   -H "Content-Type: application/json" \
   -d "{\"name\": \"Test-Event\", \"start\": \"$(date --iso-8601=minutes)\", \"end\": \"$(date --iso-8601=minutes -d '+2 hours')\"}" \
   localhost:8000/api/test-kalender/event

The response will contain the event ID:

{
  "id": "4zx3QAFzoxV3vaZSKGaH2S"
}

Delete an event

To delete an event, you need to send a DELETE request to /api/{calendar}/events/{event_id}.

Curl example:

curl -s -X DELETE \
  -H "Authorization: Bearer secrettoken" \
  -H "Content-Type: application/json" \
  localhost:8000/api/test-kalender/event/4zx3QAFzoxV3vaZSKGaH2S

The response will be empty but the status code will be 204.

Clear colliding and canceled events

To clear colliding and canceled events, you can run the clear_bookings.py script.

python clear_bookings.py [--calendar CALENDAR] [--dry-run DRY_RUN]

The following parameters can be passed as arguments:

• --calendar: The calendars to clear collisions events from. If not specified, all calendars (marked for auto clearing) will be cleared.
• --dry-run: If set, the script will only simulate the clearing and not actually delete any events.

Execute script as short-lived docker container:

docker compose -f path/to/docker-compose.yaml run --rm room-booking python clear_bookings.py

Email Notifications

The organizer of the events will be notified via email about the deletion of their event if an email template is configured for the calendar.

The following environment variables can be set to configure the application:

• SMTP_EMAIL - The email address to use as the sender for notification emails.
• SMTP_PASSWORD - The password for the SMTP email account.
• SMTP_SERVER - The SMTP server to use for sending emails.
• SMTP_USER_NAME - The username for the SMTP email account. If not set, the SMTP_EMAIL will be used as the username.
• SMTP_SENDER_NAME - The name to use as the sender for notification emails.
• SMTP_BCC - A comma-separated list of email addresses to BCC on notification emails.
• SMTP_STARTTLS - Whether to use STARTTLS for the SMTP connection. Defaults to False, so SSL is used instead.
• SMTP_PORT - The port to use for the SMTP connection. Defaults to 465 for SSL and 587 for STARTTLS.

Email Template Variables

Email templates can be configured in the Django Admin interface. Jinja2 syntax is used for the templates. The following variables are available in the templates:

• booking - The booking that was declined
• calendar_name - The name of the calendar

Lists

• colliding_bookings - A list of colliding bookings
• other_bookings - A list of other bookings at the same day(s) as the declined
• overview - A list of all bookings in the calendar for the day(s) of the declined booking
• alternatives - List of alternative calendars (rooms) for the time slot of the

Attributes

Each event has the following attributes:

• uid - The unique ID of the event
• name - The name of the event
• start - The start time (datetime) of the event
• end - The end time (datetime) of the event
• duration - The duration of the event (timedelta)
• created - The datetime the event was created
• status - The status of the event
• organizer - The organizer of the event
• is_cancelled - Whether the event was cancelled
• is_recurring - Whether the event is recurring
• is_prioritized - Whether the event is prioritized
• is_deleted - Whether the event was deleted
• is_deprioritized - Whether the event is deprioritized in favor of another
• is_collision - Whether the event is a collision with the booking
• is_other_booking - Whether the event is another booking at the same day(s) as the booking but not colliding.
• is_declined - Whether the event was declined due to a collision