Calven supports several interconnected models of desk booking, in-office presence and plans (whether you are in-office, remote or on leave on a given day). Calven also has a specific model of how office locations, levels, zones (neighborhoods) and desks are stored. This document provides an overview of those models, which is important for utilizing the information returned in the data warehouse APIs.

Calven Locations

Calven office locations have a specific hierarchy:

Location (often called an office)

Level

Zone (often called a neighborhood)

Place (often called a desk)

Each place must be stored in a zone, which must be in a level, which must be in a location.

Calven plans

Employees using Calven will set their plans for each weekday. The plans can be one of:

(O)ffice - in one of the company locations

(R)emote - meaning you are working from home or another remote site

(A)way - meaning you are not working

An employee can only have one plan on a given day. When an employee is in an office they can have an associated booking with that plan. If an employee has a booking and they switch their plan to be remote, their associated booking will be cancelled.

Calven Bookings

When an user has a plan of Office, they will have an associated booking for that day. That booking can be one of three types:

Location booking

Zone booking

Place booking

A location booking indicates that the user will be in the office but they have not booked a specific desk resource for that day.

A zone booking is a reservation for a desk resource in a zone (neighborhood) that is configured for neighborhood-based booking, which manages capacity in a neighborhood but does not reserve a specific desk.

A place booking is a reservation for a specific desk resource in a zone (neighborhood) that is configured for individual desk booking.

A user can only have one booking for a specific day, so if the user books another desk then their original booking will be removed.

Presence

Presence reporting for users is done via integrated office systems. Those systems can be WiFi, badge systems or anything else that can report when a user is in the office. If you want to integrate your own data, you can send it via the POST /presence endpoint.

When presence is reported for a user, it only needs to be reported once per day, and the user is considered to be 'confirmed' as having attended the office.

It is perfectly fine for multiple presence systems to be reporting presence for users. If any one system reports presence for a user it will count as a confirmation of their presence.

Attendance

Attendance is a model that incorporates both plans and presence together. The plan is what a user indicated that they would do on a specific day, the presence is what a user actually did based on the systems detecting the user's behavior.

There are 4 states of attendance:

Unconfirmed - the user's plan indicated that they are in an office, but there is no system reporting presence for that office so their attendance could not be confirmed.

Confirmed - the user's plan indicated that they are in an office and their presence was detected.

Walk-in - the user's plan indicated that they were not going to be in the office (meaning they were remote, away or in another office) but their presence was detected.

No-show - the user's plan indicated they were going to be in the office but they were not detected.

If a user planned to be remote/away and they were not detected, then they would not have an attendance state for that day.

Putting it all together

The combination of these models is reported on the (GET /v1/analytics/user-booking-attendance/) endpoint, with the bookings & attendance data for a user & day reported on a single row.

Calven Data Models

Calven Locations#

Calven plans#

Calven Bookings#

Presence#