> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Upcoming maintenance and the calendar feed

> Show scheduled maintenance on a status page and let visitors subscribe to it in Google Calendar, Apple Calendar, or Outlook.

Published maintenance windows appear on the status page in an **Upcoming
maintenance** section, and every page publishes the same windows as a
calendar feed that visitors can subscribe to. Both read the same data, so
they always agree.

## The Upcoming maintenance section

The section lists maintenance windows that:

* are published (drafts never show);
* have not started yet (a window in progress is shown at the top of the page
  instead);
* start within the next 60 days.

Up to 10 windows show, soonest first. Each row shows the title, the scheduled
window in the page's timezone, how soon it starts ("Today", "Tomorrow", "In 5
days"), and the affected services, and links to the window's permalink
(`/incidents/<id>`). The section header has an **Add to calendar** link to
the calendar feed.

When nothing is scheduled, the section is not rendered at all, so it is safe
to leave on.

### Show, hide, or move the section

<Steps>
  <Step title="Open the layout settings">
    In the console, open the page in the page editor and go to **Layout**. The
    section list shows every section of the page in order.
  </Step>

  <Step title="Show or hide it">
    Use the eye toggle on the **Upcoming maintenance** row. The section is on
    by default, including on pages created before it existed.
  </Step>

  <Step title="Reorder it (Pulse and Blueprint layouts)">
    Drag the row by its handle, or use the arrow buttons. By default the section
    sits directly above the incident list. The Aurora layout uses a fixed section
    order: there you can only show or hide it.
  </Step>

  <Step title="Save">
    Click **Save**. The public page updates on its next render.
  </Step>
</Steps>

## The calendar feed

```text theme={null}
https://<subdomain>.use.observer/calendar.ics
```

The feed also works on a page's custom domain once it is active, for example
`https://status.example.com/calendar.ics`. Links and event identifiers in the
feed then use the custom domain.

### What it contains

One event per published maintenance window that ends no more than 30 days
ago, plus every upcoming window. Each event has:

* **Title**: `Maintenance: <title>`.
* **Start and end**: the scheduled window (in UTC; calendar apps convert to
  the viewer's timezone).
* **Description**: whether the window is in progress, complete, or canceled,
  the affected services, the latest update, and a link to the window's
  permalink.
* **Link**: the window's permalink on the status page.
* **Status**: confirmed, or cancelled for a canceled window.
* **Free/busy**: free. Maintenance events do not block the subscriber's time.

Canceled windows stay in the feed, marked as cancelled, so subscribed
calendars remove or strike out the event instead of keeping a stale one.
Edits to a window (a new time, an update) replace the existing event rather
than adding a second one.

The feed applies the same visibility rules as the page: drafts and deleted
windows are excluded, and customer-scoped windows appear only for the
customer they are scoped to.

## Subscribe in a calendar app

Subscribe by URL rather than importing the file. A subscription keeps
refreshing; an import is a one-time copy.

<Tabs>
  <Tab title="Google Calendar">
    1. On a computer, open Google Calendar.
    2. Next to **Other calendars**, click **+**, then **From URL**.
    3. Paste the feed URL and click **Add calendar**.
  </Tab>

  <Tab title="Apple Calendar">
    1. In Calendar on a Mac, choose **File**, then **New Calendar Subscription**.
    2. Paste the feed URL and click **Subscribe**.
    3. Pick an auto-refresh interval, then click **OK**.

    On iPhone or iPad, open **Settings**, **Calendar**, **Accounts**, **Add
    Account**, **Other**, **Add Subscribed Calendar**, and paste the URL.
  </Tab>

  <Tab title="Outlook">
    1. In Outlook on the web, open the calendar.
    2. Click **Add calendar**, then **Subscribe from web**.
    3. Paste the feed URL, give the calendar a name, and click **Import**.
  </Tab>
</Tabs>

### Refresh behaviour

The feed asks calendar apps to refresh every hour, and the page serves it
with a five-minute cache. Each calendar app decides how often it actually
re-fetches: some honour the hourly hint, others refresh only every few
hours. A change to a window can therefore take a while to appear in a
subscribed calendar. The status page itself always shows the current
schedule.

## Restricted pages

The feed follows the page's access mode:

* **Public** pages: anyone can fetch the feed.
* **JWT** and **customer-scoped** pages: the feed requires a valid token,
  sent as a Bearer token or as `?token=` on the URL. A customer-scoped token
  returns that customer's scoped windows as well as the page-wide ones.
* **IP allowlist** pages: the request must come from an allowed address.
  Calendar apps fetch from their own servers, so this usually only works for
  clients that fetch from inside your network.
* **Password** pages: the feed is not available and answers `401`.

A refused request gets a short plain-text explanation instead of a calendar.
Responses for restricted pages are never cached by shared caches.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.