Calendar Event Schema

Event title

Event description

Event start date-time (ISO format)

Event end date-time (ISO format)

Whether this is an all-day event

How this event should be shown in free/busy lookups (Outlook-compatible). Defaults to busy for timed events, free for all-day events.

Event visibility. PRIVATE events are only visible to their creator and listed participants (participants.userId). Outlook-style private-appointment flag.

Event location

Event participants: internal users, CRM contact persons, or external emails

Grabsteine für Teilnehmer, die in Codemeta bewusst entfernt wurden — Identitätsschlüssel im Format `user:<uuid>` bzw. `email:<adresse>`. Verhindert, dass der eingehende Outlook-Abgleich sie wieder einträgt (ADR 0592). Serverseitig gepflegt: `entity-hooks/calendar_event.hooks.ts` schreibt das Feld bei jeder Änderung an `participants` neu und verwirft jeden Client-Wert.

Linked party/company UUID (Firma)

Linked ticket UUID

Linked project UUID

Linked opportunity UUID (Vertriebschance). Set when an appointment is created from the opportunity "Termine" tab; lists events for that opportunity.

Linked task UUID (ADR 0219). Typed mirror of the polymorphic referenceType:"TASK" + referenceId for symmetry with linkedProjectId/linkedTicketId/linkedOpportunityId. Readers should prefer this and fall back to (referenceType === "TASK" ? referenceId : null) for older events that only carry the polymorphic pair.

Linked performance_review UUID. When set, changes to this event mirror back to review.meeting and deletion resets the review to AWAITING_MEETING.

ADR 0310: optional project_position this appointment is billed against, mirroring task.positionId. null = no position (free appointment). Set from the project "Termine" tab so it is clear which position (and thus billingModel flat_rate/time_and_material) time booked off this event belongs to; the positionId is carried onto the time booking when the appointment is verbucht.

Linked party address UUID — references an address entry within the linked party (for on-site appointments)

Linked internal location UUID (building/room from locations entity)

ADR 0507: what kind of place the event happens at. CUSTOMER = address of the linked party (partyAddressId), OWN = one of the MSP own locations (ownAddressId), ONLINE = remote/video call without postal address. Missing on legacy events — readers derive it via resolveEventLocationMode().

ADR 0507: id of the selected own-company location (self-company party addresses[]._id as served by GET /self-company-locations). Only meaningful when locationMode = OWN.

Travel time before event in minutes (Anfahrt)

Travel time after event in minutes (Abfahrt)

True when travel times were auto-computed from party.travelConfig / OpenRouteService. Set to false to suppress future auto-updates.

One-way distance in km between self-company location and customer address, captured from OpenRouteService alongside travelBeforeMinutes/travelAfterMinutes. Displayed on the Anfahrt/Abfahrt strips in the calendar.

Polymorphic reference type (Auftrag) — same as time records. HR_TICKET links events to an internal HR-Ticket (Onboarding-Termin, Probezeit-Review, ...). TRAINING_SESSION links auto-generated calendar entries to a Schulungsgruppe (WP-F). OPPORTUNITY links the event to a Vertriebschance; the dialog mirrors the id into linkedOpportunityId so the opportunity "Termine" tab and feed keep working off the typed field.

Polymorphic reference ID (Auftrag) — same as time records

Affected asset/device UUIDs (betroffene Geräte) — lets one appointment cover multiple assets (e.g. updating several firewalls/servers). Independent of the single "Auftrag" referenceType/referenceId, which stays the primary Vorgang (ticket/project/asset).

Reserved vehicle UUIDs (Fahrzeuge) — prevents double-booking

Fleet driver UUID — set when event is a vehicle reservation

Reservation workflow status — relevant when linkedVehicleIds or linkedResourceIds is set

Purpose/reason for the reservation

ADR 0836: a vehicle is needed for this appointment. Open demand while linkedVehicleIds is empty; stays true after a vehicle is assigned so that removing the vehicle re-opens the demand.

ADR 0836: preferred fleet pool (pool NAME as in vehicle.poolGroup). Hint for the dispatcher, not a constraint.

ADR 0857: managed_event this room block belongs to

ADR 0857: EVENT = the event itself; SETUP/TEARDOWN block the room without being billed ("blockiert ≠ berechnet")

ADR 0857: rank of a REQUESTED block — 1 holds the slot, 2 waits behind it. Null on a REQUESTED block = unranked inquiry.

ADR 0857: when an option lapses; the next rank moves up

Reserved pool resource UUIDs (rooms, devices, tools) — prevents double-booking

Denormalized resource name for display

Category of the linked pool resource (denormalized)

User who booked the resource (may differ from event creator)

Denormalized booker name for display

Half-day mode for HALF_DAY booking resources

Number of attendees (room bookings)

Whether catering was requested

Catering requests

Room setup instructions

Reason for cancellation

When the booking was cancelled

User who cancelled the booking

Reserved tool/equipment UUIDs (Werkzeug)

Planned materials for this event (linked to articles)

Microsoft Graph Calendar event ID (synced from Outlook)

Microsoft Graph iCalUId — stable, mailbox-independent meeting identifier used to deduplicate the same meeting across attendees and across event-id rotation (ADR 0168)

Microsoft Graph changeKey for echo-suppression

Teams meeting join URL

Whether this event includes a Teams meeting

Opt-in Outlook invitation for an appointment WITHOUT Teams (ADR 1008). When true, the organizer mailbox hosts the appointment as a meeting with attendees: Exchange invites the participants (subject to the tenant policy settings.calendar.inviteParticipants) and mails their updates and cancellations — exactly like a Teams meeting, but without an online meeting. Missing or null means false. Settable only on create; a PATCH that changes the stored value is rejected.

Origin of the calendar event

Which workflow created this event (ADR 0820). Set once at creation by the creating flow, never by the user. "repair_intake_pickup" marks the pickup appointment of a repair intake (ADR 0273 §8) — the only events that follow the repair ticket when it is reassigned. Absent on hand-made events.

Last time this event was synced with Microsoft

Server-assigned appointment number (sequence `calendar_event`, e.g. TRM-2026-00042). Protected — client values are ignored. Absent on appointments created before 2026-10-01.

Last outbound sync error message — cleared on the next successful sync. Written only by the worker (protected field).

Outbound sync state. `diverged` = Outlook refused a delete and still shows an appointment we removed here (ADR 0636/0661); mirrors dms_folder.syncState.

Recurrence pattern type

Recurrence interval (e.g. every 2 weeks)

Days of week for weekly recurrence (0=Sun, 1=Mon, ..., 6=Sat)

End date for recurrence series

Number of occurrences for recurrence series

Occurrence dates (YYYY-MM-DD, local) deleted individually out of the series. The master document itself always sits on a LIVE occurrence — deleting the FIRST one advances startAt/endAt instead of adding an exception — so day-scoped views that do not expand the series never render a cancelled date.

Per-participant occurrence removals (ADR 0714): internal userId → local YYYY-MM-DD keys the participant took out of the series FOR THEMSELVES ONLY. Server-managed via POST /calendar_events/:id/remove-occurrence; client writes are dropped. Unlike recurrenceExceptions (the organizer list, valid for everyone) this never moves the master, so the series stays intact for the other participants. Read paths return the union as the computed field viewerRecurrenceExceptions.

UUID grouping events in the same recurrence series

Reminders before event start (notification triggers)

Reference to the booking link used

Reference to the booking service

Customer first name (denormalized)

Customer last name (denormalized)

Customer email (deduplication key for party)

Customer phone in E.164-like format

Customer company name

Custom field answers from the booking form

SHA-256 hash of the self-service management token

Expiry of the management token

How the booking was created

When the booking was confirmed

userId or "auto"

Who initiated the cancellation

IANA timezone of the customer at booking time

Customer IP address (audit only, not exposed in API)

Customer user agent (audit only, not exposed in API)

Number of participants for group bookings

Optional list of participant names for group bookings

Whether this is a group booking slot

When the follow-up email was sent

NPS rating (0-10) provided by customer after appointment

Free-text feedback from NPS follow-up

Server-maintained reschedule-policy tracking (ADR 0342, protected field). Absent on events that were never policed — readers must treat absence as crossDayMoveCount 0 (no backfill).