Run the occurrence optimiser

In this article

Before you start

• The operator is signed in with Harbor Demo Group and Harbor Soho as the active organisation and location.
• A Harbor Soho service occurrence exists, such as Soho lunch service, and belongs to the selected location.
• The service occurrence resolves to a floor plan and an optimisation configuration.
• Automatic reservation use is enabled for the location, and the external optimiser backend is configured.
• In the current UI, the operator needs reservation management access at the location to open Configuration.

Instructions

1. 1.

   Open the service occurrence

   Open the Harbor Soho service occurrence from the reservations calendar. In the demo runtime, use the Soho lunch service occurrence identified by `BOOKING_SOLUTIONS_OCCURRENCE_ID`.

2. 2.

   Check readiness

   Confirm the occurrence belongs to a service event and that the screen can resolve its floor plan and optimisation configuration. The operator does not choose those settings in this flow; Antylogic reads them from the service occurrence and service event.

3. 3.

   Start proposed layouts

   Open Configuration and choose Proposed layouts. If the service is manual, the cache is not fresh or no last run exists, the screen requests a fresh run with `force=true`; otherwise it sends `force=false` so the backend can reuse a valid cached run.

4. 4.

   Wait for the result

   When a fresh run is needed, Antylogic builds the optimiser payload from the configuration, floor plan tables, table combinations, active reservations and existing assignments, then records the run as a manual request.

5. 5.

   Review proposed layouts

   If the run returns solutions, the Proposed layouts modal opens with solution cards showing score, objective, split count and suggested table or time assignments for reservations such as Liam Scott in the Harbor Soho demo data.

6. 6.

   Stage separately if needed

   Use Preload in schedule only when the operator wants to preview one proposed layout in the schedule. Saving those staged assignments is a separate table-assignment flow, not part of `optimization.run`.

Validations and limits

• `POST /api/app/{orgId}/{locationId}/service-occurrences/{occurrenceId}/optimization/runs` only supports `force?: boolean`; an empty body is accepted and malformed JSON is rejected.
• The occurrence id must be present, must belong to the active Harbor Soho location and must resolve to a service occurrence.
• The service needs a resolvable `layout_id` and `optimization_config_id`; the layout must belong to the same location and optimisation settings must be parseable.
• If the service has no optimisation configuration, the UI shows an availability notice and does not call the endpoint.
• The current UI exposes the action through `reservation:manage`; the backend accepts `optimization:view`, `reservation:manage` or `optimization:manage`, and also requires `reservation-automatic:use`.
• With `force=false`, a fresh cache and a valid `optimization_last_run_id`, the backend can return the stored `OptimizationRunSummary` without calling the external optimiser.
• Cancelled and waitlist reservations are omitted from the optimiser payload; active reservations and existing table assignments are used to calculate proposals.
• The modal opens only when the returned summary includes at least one solution. If there are no applicable solutions, the UI shows a notice instead.
• If the optimiser backend is not configured or the run fails, the UI shows the resolved error. The occurrence falls back to manual handling only after a deterministic failure (400, 401 or a response the backend cannot read); a proven infeasibility (422 `infeasible`) or a transient failure (503, 500, network or timeout) leaves the booking mode unchanged.

Expected result

The operator receives an `OptimizationRunSummary` with proposed layouts, metrics and suggested assignments. No reservation is created, cancelled or permanently assigned by this action.