Update a service with roles and employees

In this article

Before you start

• Work inside the correct organisation and location, for example Harbor Demo Group and Harbor Soho.
• Have `service:view` and `staff-schedule:view` before opening an existing service bundle.
• Have `service:manage` to create or update the service bundle.
• Have `staff-schedule:manage` when the bundle contains employee schedules or existing schedules need to be synchronised.
• For an existing service, open a `calendar_event` with `kind=service` that belongs to the active location and has not already started.
• For a public service, make sure a floor plan and catalogue are selected; internal services can be saved without those public-booking resources.
• Create staff roles before adding role requirements, and create employees before assigning service schedules.

Instructions

1. 1.

   Open the service form

   Open the services calendar and create a new service or edit an existing service occurrence. In the GB demo, Harbor Soho uses `SERVICE_EVENT_ID` and `SERVICE_OCCURRENCE_START` for the seeded Soho lunch service.

2. 2.

   Check the service information

   On the Info tab, review the title, start time, end time and visibility. For a public service, keep the floor plan and Soho Menu catalogue selected; use internal visibility only for staff planning that does not need public booking resources.

3. 3.

   Set the required roles

   Open Required roles and add one row for each role needed in the service. Set the minimum and recommended coverage for roles such as floor, kitchen and bar; the form prevents the same role being added twice.

4. 4.

   Assign employees

   Open Employees and assign each staff member to a role and timing mode. Relative timing stores the shift as offsets from the service start and end; absolute timing uses its own start and end times.

5. 5.

   Save the bundle

   Select Save. A new service uses `POST /api/app/{orgId}/{locationId}/calendar-events/service-bundle`; a normal edit uses `PUT /api/app/{orgId}/{locationId}/calendar-events/{eventId}/service-bundle`. The service event, role requirements and employee schedules are saved together.

6. 6.

   Choose a recurring scope when asked

   If the service is recurring, saving opens the recurring update prompt. Choose whether the change applies only to the selected occurrence or to this and future services; the app then saves through the recurring split flow.

7. 7.

   Review the refreshed calendar

   After a successful save, Antylogic shows success, displays any operation warnings, refreshes calendar and bundle data, and returns to the services calendar.

Validations and limits

• The bundle only applies to service events; the event type cannot be changed through this flow.
• Services that have already started cannot be edited.
• The service and any absolute employee schedule need valid start and end times, with the start before the end.
• Visibility must be `public` or `internal`; public services require valid `layout_id` and `catalog_id` values.
• Each required role row needs a staff role, and duplicate roles are rejected.
• The form keeps minimum and recommended role counts as whole numbers of at least 1.
• Each employee schedule needs a staff member and a role in its payload, linked back to the parent service.
• Relative schedules need integer start and end offsets; absolute schedules use start and end times and do not include relative offsets.
• Removing a role or employee row from the form removes that requirement or schedule from the saved bundle on the next save.
• Coverage problems are returned when assignments are below the minimum requirement, and warnings are returned when they are below the recommended requirement.

Expected result

The service is saved as one transactional bundle. Service details, role requirements and employee schedules stay synchronised, coverage warnings remain visible to the operator, and the services calendar reloads with the latest plan.