Run optimiser proposals for a service occurrence

In this article

Before you start

• The operator is signed in to `Harbor Demo Group` and working in `Harbor Soho`.
• The service occurrence belongs to the active location and is linked to a service event.
• The occurrence or service event resolves both a floor plan and an optimiser configuration.
• The floor plan has tables available; configured table combinations are included.
• The operator can manage bookings from the occurrence detail screen, and the backend allows optimiser access plus `reservation-automatic:use`.
• The external optimisation service is configured if Antylogic needs to create a fresh run instead of reusing a cached one.

Instructions

1. 1.

   Open the service occurrence

   From the reservations calendar, open the Harbor Soho service occurrence that needs proposed table layouts. Confirm that the page is for the right location and service before starting the optimiser flow.

2. 2.

   Open Proposed layouts

   Use Settings on the occurrence detail page and choose Proposed layouts. The operator does not manually select the bookings sent to the optimiser; Antylogic works from the persisted bookings for this occurrence.

3. 3.

   Let Antylogic run or reuse the optimiser

   Antylogic sends a fresh-run request when the occurrence is in manual mode, the cache is not fresh or there is no previous run. When the cache is fresh, the backend can reuse the latest run instead of creating another run record.

4. 4.

   Review the alternatives

   When solutions are returned, the Proposed layouts modal opens. Review the alternative cards, score, objective value, split count and booking-by-booking table assignments before choosing what to preview.

5. 5.

   Preload the timeline

   Press Preload on timeline to preview the selected proposal in the occurrence timeline. This is only a preview of the suggested layout, not a permanent table assignment update.

Validations and limits

• The run endpoint accepts `POST` only: `/api/app/{orgId}/{locationId}/service-occurrences/{occurrenceId}/optimization/runs`.
• The request body may be empty; when present, the only supported option is `force`. The `occurrenceId` comes from the URL.
• The occurrence must belong to the active `locationId` and its linked calendar event must be a service event.
• The occurrence or service event must resolve `layout_id` and `optimization_config_id`; the layout must belong to the same location.
• The optimiser configuration must exist and its settings must be parseable before Antylogic can build the optimiser payload.
• The backend requires one of `optimization:view`, `reservation:manage` or `optimization:manage`, plus `reservation-automatic:use`.
• Cancelled and waitlist bookings are excluded from the optimiser payload.
• `force: false` allows reuse of a fresh cached run; `force: true` asks Antylogic to create a new run.
• If the optimiser returns no alternatives, the app shows an informational message and does not open the modal.
• This action creates or reuses proposals only. Persisting `optimizer_applied` table assignments belongs to `optimization.runs.apply-solution`.

Expected result

The operator has reviewable optimiser proposals for the service occurrence and can preview a selected alternative on the timeline. No permanent table assignment changes are saved by this action.