How to run optimiser proposals

In this article

Before you start

• Open the reservation occurrence detail screen for the active location at `/:orgId/:locationId/reservations/:occurrenceId`.
• The occurrence belongs to the active location and is linked to a service calendar event.
• The occurrence or service event has a valid `layout_id` and `optimization_config_id`.
• The optimisation configuration exists and its settings are valid JSON.
• The optimisation backend is configured, unless a fresh reusable run already exists.
• The operator can open Configurations in the location UI, which requires `reservation:manage` and no submission already in progress.
• The backend also requires the location feature `reservation-automatic:use`.

Instructions

1. 1.

   Open the service occurrence

   From the reservations calendar, open the service occurrence that needs proposed table arrangements. In the GB demo, use Harbor Soho and the occurrence referenced by `BOOKING_SOLUTIONS_OCCURRENCE_ID` for the Soho lunch service.

2. 2.

   Open Configurations

   Use the Configurations button on the occurrence detail screen. The Proposed arrangements option is shown from this menu when the operator has the required reservation management permission and the screen is not already submitting another change.

3. 3.

   Select Proposed arrangements

   Choose Proposed arrangements. Antylogic closes the menu and prepares the optimiser request for the current occurrence. If the occurrence or optimisation configuration cannot be resolved, the app shows an informative message and does not call the backend.

4. 4.

   Run or reuse the optimiser

   The app sends `POST /api/app/{orgId}/{locationId}/service-occurrences/{occurrenceId}/optimization/runs`. If a fresh automatic optimisation run already exists and the request is not forced, the backend can return that summary without calling the engine again. Otherwise it creates a new `manual_request` run.

5. 5.

   Wait for the run summary

   When a new run is needed, Antylogic stores it as running, sends settings, tables and eligible reservations to the optimiser, then marks the run as succeeded or failed. Cancelled and waitlist reservations are not included in the optimiser payload.

6. 6.

   Review proposed arrangements

   If the run returns solutions, the app opens the optimiser solutions modal and selects the stored `selected_solution_index`, or the first solution when there is no stored match. Review each alternative's score, objective value, desdobles used and proposed reservation-to-table assignments before taking any further action.

7. 7.

   Handle empty or failed results

   If no applicable solutions are found, the app shows a message and does not open the modal. If the optimiser call fails, the app shows the resolved error message. The occurrence is switched to manual mode only when the failure is deterministic (a rejected request, a misconfigured secret or a response the backend cannot read), so automatic booking does not continue with invalid optimisation data; a proven infeasibility or a transient failure leaves the booking mode unchanged.

Validations and limits

• The run endpoint accepts POST only.
• The request body may be empty or decode as `OptimizationRunRequest`; the implemented field is `force`.
• The backend accepts one of `optimization:view`, `reservation:manage` or `optimization:manage`, and also requires `reservation-automatic:use`.
• The occurrence must belong to the active location and its linked calendar event must be a service.
• `layout_id` and `optimization_config_id` are required, and the optimisation settings must parse as valid JSON.
• The backend must be able to load the layout, tables, table combinations, reservations, current assignments and optimisation configuration.
• A successful run marks the occurrence optimisation cache as fresh and stores `optimization_last_run_id`.
• A failed run records the failure class and phase and marks the optimisation cache as failed. Only a deterministic failure (400 `bad_request`, 401 `unauthorized` or a response the backend cannot read) sets booking mode to manual and records `optimization_last_error_code` as `optimize_failed`. A proven infeasibility (422 `infeasible`) records `optimizer_infeasible` and a transient failure (503 `solver_timeout` or `auth_unavailable`, 500, network or timeout) records `optimizer_unavailable`; in both cases the booking mode does not change and the next pass recalculates.
• The proposals shown in the modal are not persisted assignments; applying a run or saving a schedule draft is a separate action.

Expected result

The manager has reviewed optimiser alternatives for the service occurrence while the persisted table assignments remain unchanged.