151 lines
4.7 KiB
Markdown
151 lines
4.7 KiB
Markdown
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 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 |