Antylogic
DemoApp login

399 operational guides

Docs sections
DocsLeave and vacations
Device

How to create a vacation blackout

Block a date range for one location so staff cannot request holidays during peak periods. In the GB demo, Harbor Soho uses Peak season blackout as the seeded example.

In this article

Use a vacation blackout when a location needs to protect known busy dates before holiday requests reach the rota. The manager records the range, scope, reason and optional recurrence from the vacations calendar flow.

This active UI/API path saves a `calendar_event` with `kind: 'vacation_blackout'`; it does not use the historical `staff_vacation_blackouts` model.

Before you start

  • You are signed in with an organisation and location selected, for example Harbor Demo Group and Harbor Soho.
  • Your location permissions include `vacation-blackout:manage`; view-only access is not enough to save.
  • To block by role, staff roles must load from `GET /api/app/{orgId}/{locationId}/staff-roles`.
  • To block named staff, staff members must load from `GET /api/app/{orgId}/{locationId}/staff`.
  • Decide the blocked date range, who it applies to and the business reason before saving.

Instructions

  1. 1.

    Open the blackout form

    From the Harbor Soho vacations calendar, choose the new blackout action. The direct route is `calendars/create?kind=vacation_blackout&preset=vacations`, which opens Block vacations with Info and Repeat tabs.

  2. 2.

    Set the date range

    Review Starts and Ends. Vacation blackouts are all-day events in the dedicated form, so the start is saved at the beginning of the first day and the end at the end of the final day.

  3. 3.

    Choose who is affected

    Use Scope to apply the blackout to the whole location, selected roles or selected staff members. Changing scope clears selections that no longer apply.

  4. 4.

    Enter the reason

    Fill Reason with the operational explanation, such as Peak season blackout. This becomes `payload.reason` on the calendar event.

  5. 5.

    Add recurrence if needed

    Open Repeat only when the blackout should repeat. Leave recurrence as none for a one-off blackout, or choose a supported pattern such as weekly.

  6. 6.

    Save and verify

    Press Block. The app posts the blackout to `POST /api/app/{orgId}/{locationId}/calendar-events`, refreshes calendar event data on success and returns to the previous route. Confirm the blackout in the vacations calendar.

Validations and limits

  • The form requires active organisation and location context.
  • Creating the event requires `vacation-blackout:manage`.
  • Starts and Ends must be valid dates, and Starts must be before Ends.
  • Reason is required after trimming whitespace.
  • Role scope requires at least one `staff_role_id`; staff scope requires at least one `staff_id`; total scope must not carry role or staff selections.
  • The backend accepts only `reason`, `scope`, `staff_role_ids` and `staff_ids` inside the blackout payload.
  • Recurrence is allowed for `vacation_blackout` with `daily`, `weekly`, `monthly` or `yearly` frequencies inside accepted parameter ranges.
  • The blackout is limited to the selected `{orgId}` and `{locationId}`; it does not create a multi-location block.

Expected result

The location gets a `calendar_event` blackout. Later overlapping vacation requests are blocked when the blackout applies to the employee, with staff scope taking priority over role scope, then location-wide scope.