Create a Holiday Blackout

In this article

Before you start

• Sign in with an active organisation and location context, for example Harbor Demo Group and Harbor Soho.
• Have the location permission `vacation-blackout:manage`; `vacation:manage` and `vacation:request` do not create holiday blackouts.
• For Role scope, have `staff-roles:view` and visible staff roles for the location.
• For Staff scope, have `staff:view` and visible staff records such as Olivia Hart, Mason Reed, Noah Stone, and Ava Price.
• Open `/:orgId/:locationId/calendars/vacations` and choose Create > Block vacations, or open `/:orgId/:locationId/calendars/create?kind=vacation_blackout` directly.
• For recurrence documentation, open Repeat and choose a pattern without pressing Block.

Instructions

1. 1.

   Open the holidays calendar

   In Harbor Soho, open the holidays calendar, choose Create, and select Block vacations. The option is only available to users who can manage holiday blackouts for the selected location.

2. 2.

   Confirm the blackout dates

   The dedicated form opens as an all-day blackout using the location timezone, Europe/London for Harbor Soho. Set Start and End for the blocked period, for example 12 May 2026 to 14 May 2026.

3. 3.

   Choose the scope

   Use Location scope to block holiday requests for everyone at Harbor Soho. Use Role scope to reveal Staff roles, or Staff scope to reveal Staff members such as Olivia Hart or Noah Stone.

4. 4.

   Add the reason

   Enter the operational reason staff will see when a holiday request is blocked, for example Peak season blackout. The dedicated blackout form does not expose custom title or description fields.

5. 5.

   Set a recurrence if needed

   Open Repeat only when the same blackout should repeat. Supported patterns are daily, weekly, monthly, and yearly. Leave recurrence unset for a one-off blackout.

6. 6.

   Create the blackout

   Press Block. The app creates the blackout, shows the success message, refreshes calendar events, and returns to the holidays calendar.

7. 7.

   Review the result

   Check the holidays calendar for the new blackout. Later holiday requests that overlap an applicable blackout are rejected, with staff-specific blackouts taking priority over role blackouts, and role blackouts taking priority over location-wide blackouts.

Validations and limits

• Start and End must be valid dates, and Start must be earlier than End.
• Reason is required and cannot be blank after trimming.
• Role scope requires at least one staff role selection; Staff scope requires at least one staff member selection.
• Changing Scope clears selections that no longer apply.
• Creating a blackout requires `vacation-blackout:manage`; view-only access is not enough.
• The saved record is a `calendar_events` item with `kind=vacation_blackout`, not a `staff_vacation_blackouts` record.
• The blackout payload only supports `reason`, `scope`, `staff_role_ids`, and `staff_ids`.
• Location scope must not include role or staff ids; Role scope uses `staff_role_ids`; Staff scope uses `staff_ids`.
• Recurrence is allowed for holiday blackouts with daily, weekly, monthly, or yearly frequency; no recurrence creates only the single event.
• If local validation fails, the form does not submit. If the server rejects the request, the user stays on the form and sees the API error message.

Expected result

The holiday blackout appears in the holidays calendar as a `vacation_blackout` event. Future staff holiday requests that overlap an applicable blackout are blocked according to the selected scope.