The Calendar Scheduling extension provides a unified calendar view of all maintenance activities — inspections, interventions, and work orders — with per-user filtering and real-time assignment notifications.

Table of Contents¶

• Overview
• Extension Endpoints
• Per-User Filtering
• Assignment Notifications
• WebSocket Events
• Data Formats

Overview¶

The calendar system is implemented as a built-in extension (CalendarSchedulingExtension) that aggregates data from three entity types:

Architecture¶

Mobile/Web Client
      │
      ▼
  Extension Endpoints (/ext/calendar-scheduling/*)
      │
      ├── resolveUserId(ctx, params)  ← Determines filtering scope
      │
      ├── InspectionRepository        ← Per-user or all inspections
      ├── InterventionRepository      ← Per-user or all interventions
      └── WorkOrderRepository         ← Per-user or all work orders

Extension Endpoints¶

All endpoints are available at /ext/calendar-scheduling/ and require authentication.

GET /ext/calendar-scheduling/events¶

Returns all calendar events (inspections, interventions, work orders) within a date range.

Query Parameters:

Response:

{
  "events": [
    {
      "id": 1,
      "type": "inspection",
      "title": "Monthly turbine inspection",
      "start": "2026-01-15T09:00:00",
      "end": "2026-01-15T12:00:00",
      "status": "PLANNED",
      "priority": "HIGH",
      "assignees": ["John Doe", "Jane Smith"],
      "assigneeIds": [42, 55],
      "unitName": "Turbine A1",
      "color": "#4CAF50"
    }
  ]
}

GET /ext/calendar-scheduling/inspections¶

Returns only inspections within a date range.

GET /ext/calendar-scheduling/interventions¶

Returns only interventions within a date range.

GET /ext/calendar-scheduling/work-orders¶

Returns only work orders within a date range.

GET /ext/calendar-scheduling/upcoming¶

Returns upcoming events within the next N days (default: 7).

GET /ext/calendar-scheduling/overdue¶

Returns overdue work orders (past scheduledEndDate, not completed/closed/cancelled).

GET /ext/calendar-scheduling/summary¶

Returns event counts grouped by type and status for a date range.

GET /ext/calendar-scheduling/settings¶

Returns calendar display settings (colors, default views).

Per-User Filtering¶

By default, all data endpoints filter events to the authenticated user only. This ensures field technicians see only their own schedule.

How It Works¶

The resolveUserId() helper determines the filtering scope:

1. No userId param → Uses ctx.getUserId() (current authenticated user)
2. userId=all → No filtering, returns all events (for admin/manager views)
3. userId=42 → Filters to specific user ID (for managers viewing a technician's schedule)

User Matching Rules¶

Repository Queries¶

Efficient JPQL queries with JOINs are used to filter at the database level (not in-memory):

// Inspections
SELECT i FROM Inspection i JOIN i.users u
WHERE u.id = :userId AND i.plannedDate BETWEEN :start AND :end

// Interventions
SELECT i FROM Intervention i JOIN i.users u
WHERE u.id = :userId AND i.scheduleDate BETWEEN :start AND :end

// Work Orders (checks both assignedTo and technicians)
SELECT DISTINCT wo FROM WorkOrder wo LEFT JOIN wo.technicians t
WHERE (wo.assignedTo.id = :userId OR t.id = :userId)
AND wo.status IN :statuses AND wo.scheduledStartDate BETWEEN :start AND :end

Assignment Notifications¶

When technicians are assigned to work orders, interventions, or inspections, the system automatically sends in-app notifications and WebSocket calendar refresh events.

Trigger Points¶

Notification Flow¶

Service.create() / Service.update()
      │
      ├── Compute new assignees (diff old vs new)
      │
      └── AssignmentNotificationService (async)
              │
              ├── NotificationService.createNotification()
              │       → Persists in-app notification
              │       → Pushes via WebSocket /user/queue/notifications
              │
              └── WebSocketService.sendCalendarUpdate()
                      → Pushes via WebSocket /user/queue/calendar

New Assignee Detection¶

For create operations, all users in the entity are considered "new."

For update operations, the service: 1. Loads the old entity within the current transaction 2. Force-initializes lazy collections with Hibernate.initialize() 3. Compares old user set vs new user set 4. Only users in newSet - oldSet receive notifications

Notification Content¶

In-App Notification (persisted to DB):

{
  "title": "New Work Order Assignment",
  "message": "You have been assigned to work order WO-1706745600",
  "type": "ASSIGNMENT",
  "referenceType": "WORK_ORDER",
  "referenceId": 42
}

WebSocket Calendar Update (ephemeral):

{
  "action": "ASSIGNMENT",
  "entityType": "WORK_ORDER",
  "entityId": 42,
  "timestamp": "2026-02-11T14:30:00"
}

WebSocket Events¶

Calendar Updates Channel¶

Destination: /user/queue/calendar

Sent when a user is newly assigned to a maintenance entity. The client should refresh its calendar view upon receiving this event.

Notifications Channel¶

Destination: /user/queue/notifications

Standard notification channel. Assignment notifications are pushed here alongside other notification types.

Data Formats¶

Event Colors¶

Work Order Priority Colors¶

Event Map Fields¶

All calendar events share these common fields:

Implementation Details¶

Key Classes¶

Async Processing¶

Assignment notifications run asynchronously on the notificationExecutor thread pool to avoid blocking the main request thread. This means: - The HTTP response returns immediately after save - Notifications are delivered in the background - If notification delivery fails, the entity save is not rolled back