---
title: "Maintenance Events"
description: "Understanding maintenance events: automatic generation, lifecycle states, and status transitions in Kener."
---

Maintenance events are the individual occurrences of a maintenance window. This guide explains how events are generated, their lifecycle, and how they transition between states.

## What is a Maintenance Event? {#what-is-event}

A maintenance event represents a single occurrence of a maintenance window. Each event has:

- **Start Date/Time** - When this occurrence begins
- **End Date/Time** - When this occurrence ends (start + duration)
- **Status** - Current state (SCHEDULED, READY, ONGOING, COMPLETED, CANCELLED)
- **Maintenance ID** - Links back to the parent maintenance

**Relationship:**

```
Maintenance (1) → Events (many)
"Weekly Updates" → [Event 1, Event 2, Event 3, ...]
```

## Automatic Event Generation {#automatic-generation}

Events are created automatically by Kener based on the maintenance type and schedule.

### One-Time Maintenances {#one-time-generation}

**When:** Event created immediately when maintenance is created

**How Many:** Exactly 1 event

**Example:**

```
Maintenance: Database Migration
RRULE: FREQ=MINUTELY;COUNT=1
Start: May 15, 2026 at 2:00 AM
Duration: 3 hours

Generated Event:
- Start: May 15, 2026 at 2:00 AM
- End: May 15, 2026 at 5:00 AM
- Status: SCHEDULED
```

### Recurring Maintenances {#recurring-generation}

**When:**

- Initial events created when maintenance is created
- New events generated every hour by scheduler

**How Many:** Events for the next 7 days

**Example:**

```
Maintenance: Weekly Security Updates
RRULE: FREQ=WEEKLY;BYDAY=SU
Start: May 15, 2026 at 3:00 AM
Duration: 1 hour

Generated Events (assuming today is May 10):
1. May 15, 3:00 AM - 4:00 AM (SCHEDULED)
2. May 22, 3:00 AM - 4:00 AM (SCHEDULED)
3. May 29, 3:00 AM - 4:00 AM (SCHEDULED)
4. June 5, 3:00 AM - 4:00 AM (SCHEDULED)
```

**Rolling Window:**
The scheduler runs every hour and ensures there are always events for the next 7 days:

- Today is May 15 → Events through May 22 exist
- Tomorrow (May 16) → Scheduler creates event for May 23
- Continuous 7-day lookahead

### Duplicate Prevention {#duplicate-prevention}

The system prevents duplicate events:

1. Check if event for specific start time already exists
2. Skip creation if duplicate found
3. Only create missing events

This ensures the hourly scheduler doesn't create duplicates.

## Event Lifecycle States {#event-lifecycle}

Every maintenance event progresses through a series of states that track its progress.

### State Diagram {#state-diagram}

```
SCHEDULED → READY → ONGOING → COMPLETED
    ↓          ↓        ↓
  [CANCELLED at any point]
```

### State Descriptions {#state-descriptions}

#### SCHEDULED {#scheduled-state}

**When:** Event created, more than 60 minutes until start time

**Meaning:**

- Maintenance is scheduled but not imminent
- Visible to users in upcoming maintenances
- No notifications sent yet

**Displayed As:** "Scheduled" or "In X hours/days"

**Example:**

```
Current Time: May 15, 12:00 PM
Event Start: May 15, 3:00 PM
Status: SCHEDULED (3 hours away)
```

#### READY {#ready-state}

**When:** Current time is within 60 minutes of start time

**Meaning:**

- Maintenance starting soon
- Advance notification sent to subscribers
- Monitor status not yet overridden

**Displayed As:** "Starting soon" or "In X minutes"

**Notification:** "Maintenance Starting Soon" notification sent

**Example:**

```
Current Time: May 15, 2:15 PM
Event Start: May 15, 3:00 PM
Status: READY (45 minutes away)
Action: Send notification
```

**Automatic Transition:**

```
SCHEDULED → READY
Condition: (current_time + 60 minutes) >= start_time
Executed by: Status update scheduler (runs every minute)
```

#### ONGOING {#ongoing-state}

**When:** Current time is between start time and end time

**Meaning:**

- Maintenance is actively happening
- Monitor statuses overridden to configured impact levels
- Shown prominently on status page

**Displayed As:** "Ongoing" or "In progress"

**Notification:** "Maintenance In Progress" notification sent

**Example:**

```
Current Time: May 15, 3:30 PM
Event Start: May 15, 3:00 PM
Event End: May 15, 4:00 PM
Status: ONGOING (30 minutes in, 30 minutes remaining)
Action: Override monitor statuses
```

**Automatic Transition:**

```
READY → ONGOING
Condition: current_time >= start_time AND current_time < end_time
Executed by: Status update scheduler (runs every minute)
```

#### COMPLETED {#completed-state}

**When:** Current time is past end time, or an admin completes an ONGOING event early

**Meaning:**

- Maintenance has finished
- Monitor statuses restored to realtime values
- Historical record

**Displayed As:** "Completed"

**Notification:** "Maintenance Completed" notification sent

**Example:**

```
Current Time: May 15, 4:05 PM
Event End: May 15, 4:00 PM
Status: COMPLETED (finished 5 minutes ago)
Action: Restore monitor statuses
```

**Automatic Transition:**

```
ONGOING → COMPLETED
Condition: current_time >= end_time
Executed by: Status update scheduler (runs every minute)
```

**Manual Completion:**

An ONGOING event can be completed early from the maintenance edit page or via the API (see [Completing an Event Early](#completing-events)). Its end time is moved to the moment it was completed, so the recorded window reflects what actually happened.

#### CANCELLED {#cancelled-state}

**When:** Manually cancelled by an admin (allowed for SCHEDULED, READY, and ONGOING events)

**Meaning:**

- The occurrence was called off — before or during its window
- Monitor statuses are not (or no longer) overridden
- Kept in history, explicitly marked as cancelled vs completed

**Time Handling:**

- Cancelled before start: the planned window is kept unchanged
- Cancelled while ONGOING: the end time is moved to the moment of cancellation

**Displayed As:** "Cancelled"

**Notification:** "Maintenance Cancelled" notification sent (controlled by the same "ended" notification setting as completion)

> [!NOTE]
> COMPLETED and CANCELLED are terminal — an event cannot be moved out of them. For recurring maintenances, a cancelled occurrence is never regenerated, so cancelling is how you skip one occurrence while keeping the schedule.

## Automatic Status Transitions {#automatic-transitions}

Kener runs a scheduler **every minute** that updates event statuses based on the current time.

### Transition Logic {#transition-logic}

**SCHEDULED → READY:**

```javascript
// Find events where:
status === 'SCHEDULED' AND
start_date_time > current_time AND
start_date_time <= (current_time + 3600) // 60 minutes in seconds

// Update to READY
// Send "starting soon" notification
```

**READY → ONGOING:**

```javascript
// Find events where:
status === 'READY' AND
start_date_time <= current_time AND
end_date_time >= current_time

// Update to ONGOING
// Send "in progress" notification
// Override monitor statuses
```

**ONGOING → COMPLETED:**

```javascript
// Find events where:
status === 'ONGOING' AND
end_date_time < current_time

// Update to COMPLETED
// Send "completed" notification
// Restore monitor statuses
```

### Scheduler Details {#scheduler-details}

**Frequency:** Every minute

**Purpose:**

1. Update event statuses based on time
2. Send appropriate notifications
3. Trigger monitor status overrides/restores

**Implementation:**
Runs as part of `UpdateMaintenanceEventStatuses()` in maintenance controller

## Event Notifications {#event-notifications}

Notifications are triggered during state transitions:

### Notification Types {#notification-types}

**Starting Soon (SCHEDULED → READY):**

```
Subject: Maintenance Starting Soon
Body: "{title} is starting in {time_until_start}"
Monitors: List of affected monitors with impacts
When: 60 minutes before start
```

**In Progress (READY → ONGOING):**

```
Subject: Maintenance In Progress
Body: "{title} is now in progress"
Monitors: List of affected monitors with impacts
When: At start time
```

**Completed (ONGOING → COMPLETED):**

```
Subject: Maintenance Completed
Body: "{title} has been completed"
Monitors: List of affected monitors with impacts
When: At end time, or immediately when completed early
```

**Cancelled (manual cancellation):**

```
Subject: Maintenance Cancelled
Body: "{title} has been cancelled"
Monitors: List of affected monitors with impacts
When: Immediately when an admin cancels the event
```

Completed and Cancelled notifications share the same "ended" notification setting.

### Notification Channels {#notification-channels}

Notifications are sent based on your subscription configuration:

- Email (if enabled)
- Webhooks (if configured)
- Slack (if configured)
- Discord (if configured)

Only users subscribed to maintenance updates receive notifications.

## Viewing Events {#viewing-events}

### Dashboard View {#dashboard-view}

On the maintenance edit page:

1. Scroll to **Maintenance Events** section
2. Events listed in chronological order
3. Current/next event highlighted
4. Shows status, dates, and duration

**Event Display:**

```
┌─────────────────────────────────────┐
│ [SCHEDULED] Scheduled               │
│ May 22, 2026 03:00 → 04:00          │
│ Duration: 1h                        │
├─────────────────────────────────────┤
│ [ONGOING] Ongoing (Current)         │
│ May 15, 2026 03:00 → 04:00          │
│ Duration: 1h                        │
├─────────────────────────────────────┤
│ [COMPLETED] Completed               │
│ May 8, 2026 03:00 → 04:00           │
│ Duration: 1h                        │
└─────────────────────────────────────┘
```

### Status Page View {#status-page-view}

Users see events on the public status page:

**Ongoing Maintenances:**

- Prominently displayed on home page
- Affected monitors show MAINTENANCE status
- Progress/countdown indicator

**Upcoming Maintenances:**

- Listed in separate section
- Shows start time and affected services
- Countdown to start

**Past Maintenances:**

- Events/history page
- Filterable by date range
- Shows completed events

## Managing Events Manually {#managing-events-manually}

### Completing an Event Early {#completing-events}

If the maintenance work finishes before the scheduled end:

1. Find the ONGOING event on the maintenance edit page
2. Click **Complete**
3. Confirm

The event moves to COMPLETED, its end time is set to the current time, monitor statuses return to realtime values, and the completion notification is sent.

Via the API: `PATCH /api/v4/maintenances/{maintenance_id}/events/{event_id}` with body `{"status": "COMPLETED"}`.

### Cancelling Events {#cancelling-events}

From the maintenance edit page:

1. Find the event in the list (SCHEDULED, READY, or ONGOING)
2. Click **Cancel**
3. Confirm

Via the API: `PATCH /api/v4/maintenances/{maintenance_id}/events/{event_id}` with body `{"status": "CANCELLED"}`.

**When to Cancel:**

- Maintenance no longer needed
- Maintenance was aborted partway through
- Skipping one occurrence of a recurring maintenance

**Note:** Cancelled events remain in history but are not executed. A cancelled occurrence of a recurring maintenance is never regenerated.

### Deleting Events {#deleting-events}

Events can be permanently deleted:

1. Click trash icon on event
2. Confirm deletion
3. Event removed from database

**Warning:** Deletion is permanent and cannot be undone.

**When to Delete:**

- Cleaning up old historical events
- Removing erroneous events
- Database maintenance

**Best Practice:** Cancel rather than delete to preserve history.

### Editing Event Times {#cannot-edit-events}

Individual event times cannot be edited from the dashboard. To change event timing or duration:

1. Edit the parent maintenance
2. Update start time, RRULE, or duration
3. Save maintenance

**Result:**

- Future SCHEDULED events deleted
- New events generated with updated settings
- ONGOING/COMPLETED/CANCELLED events preserved

API consumers can edit a single event's window directly: `PATCH /api/v4/maintenances/{maintenance_id}/events/{event_id}` with both `start_date_time` and `end_date_time`. A request cannot combine time fields with a `status` transition.

## Event Retention {#event-retention}

Events are retained indefinitely by default:

**SCHEDULED Events:**

- Kept until executed or cancelled
- Automatically progress through lifecycle

**COMPLETED Events:**

- Kept as historical records
- Visible on status page based on page settings

**CANCELLED Events:**

- Kept as historical records
- Marked explicitly as cancelled

**Deletion:**

- Events deleted when parent maintenance is deleted
- Can be manually deleted via dashboard
- No automatic cleanup (configure if needed)

## Events and Monitor Status {#events-and-monitor-status}

During ONGOING events:

- Monitor status **overridden** to configured impact
- Realtime monitoring continues in background
- Status page shows maintenance impact

See [Maintenance Impact on Monitoring](/docs/v4/maintenances/impact-on-monitoring) for details.

## Troubleshooting {#troubleshooting}

**Problem:** Events not transitioning to READY/ONGOING

**Solutions:**

- Check scheduler is running (`npm start` in production)
- Verify system clock is accurate
- Check logs for scheduler errors

**Problem:** No events generated for recurring maintenance

**Solutions:**

- Verify maintenance status is ACTIVE
- Check RRULE is valid
- Wait for hourly scheduler to run
- Check start_date_time is not too far in future

**Problem:** Events not visible on status page

**Solutions:**

- Check page settings for visibility window
- Verify events are within configured date range
- Ensure affected monitors are not hidden

**Problem:** Too many events generated

**Solutions:**

- For one-time: Check RRULE contains `COUNT=1`
- For recurring: Events for next 7 days is expected
- Old events can be manually deleted

## Next Steps {#next-steps}

- [Maintenance Impact on Monitoring](/docs/v4/maintenances/impact-on-monitoring) - How events affect monitor status display
- [RRULE Patterns](/docs/v4/maintenances/rrule-patterns) - Advanced scheduling patterns for recurring maintenances
- [Creating and Managing Maintenances](/docs/v4/maintenances/creating-managing) - Learn how to create and edit maintenances
