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](/admin).

## Usage

A full documentation of the API is available at [`/api/docs/`](/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:

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

Curl example:

```bash
 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:

```json
{
  "id": "4zx3QAFzoxV3vaZSKGaH2S"
}
```

### Delete an event

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

Curl example:

```bash
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.

```bash
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:

```bash
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