How to review the employee list
Use the Employees tab to review active staff records for the selected location. In the GB demo, Harbor Soho lists Olivia Hart, Mason Reed, Noah Stone and Ava Price with employee role, linked-user status, email and phone. This action is read-only: creating, editing, deactivating and restoring employees are separate actions.
In this article
The Employees tab gives location managers a location-scoped staff directory. It loads staff and employee roles separately so the table can show names, role badges, linked-user badges and contact columns.
Use this guide for reading and narrowing the list. Search, role filtering and page controls happen in the app over the loaded rows; the staff list endpoint only receives the selected organisation, selected location and the inactive-record flag when it is enabled.
Before you start
- Sign in with an organisation and location selected; without both, the screen shows the location-not-found state.
- The account needs location permission `staff:view` for `GET /api/app/{orgId}/{locationId}/staff`.
- To show employee role names, colours and role filter options, the account also needs `staff-roles:view` for `GET /api/app/{orgId}/{locationId}/staff-roles`.
- Use the GB demo runtime for the examples: Harbor Demo Group, Harbor Soho and profile `restaurant_full_v1-default-en`.
- For the management capture variant, use an account that can show `Register`, `Edit`, `Deactivate` and `Restore`, while still keeping this guide focused on read-only list behaviour.
Instructions
- 1.
Open the Employees tab
Open `location/staff?tab=staff` from the selected location. The screen stays on Employees when the user can view staff; if the route asks for another tab or the user only has role access, the visible tab can switch to Employee roles instead.
- 2.
Wait for staff and roles to load
The staff list loads from `GET /api/app/{orgId}/{locationId}/staff`. Employee roles load separately from `GET /api/app/{orgId}/{locationId}/staff-roles` so badges and the role selector can show names and colours. While either required request is loading, the page shows a loading state; if either fails, it shows a data-load error.
- 3.
Review the active staff table
By default, the table shows active employees for the current location only. In Harbor Soho, the expected demo rows are Olivia Hart, Mason Reed, Noah Stone and Ava Price. The visible columns are Name, Employee role, Linked user, Email and Phone; empty email or phone values appear as a dash.
- 4.
Use search, role filtering and page controls
Use `Search by name, email, or role` and the employee-role selector to narrow the visible rows. Page controls move through the filtered rows using a page size calculated for the viewport.
- 5.
Show inactive employees when needed
Select `Show inactive employees` when the operator needs inactive staff included in the same table. The app then sends `show_deleted=true`, adds the Status column and can show Active or Inactive rows.
- 6.
Open a row without changing the list
Selecting a row opens that employee's detail view. With staff management permission, row actions can include Edit, Deactivate and Restore; with read-only access, the main row action is View. Those mutations belong to separate guides, not to `staff.list`.
Validations and limits
- The route requires `selectedOrgId` and `selectedLocationId`; if either is missing, the operator sees `Location not found.`
- If the user has no available staff or staff-role tab permissions, the screen shows the no-access state instead of the table.
- The staff request is enabled only when organisation, location and staff-view access are present.
- The backend staff list returns an array, not server-paginated data.
- Search, role filter and page number are applied in the app over the loaded array; the backend staff endpoint does not receive them as filters.
- `staff_page` is normalised to a positive integer with a fallback of 1; `staff_page_size` exists in routing, but this screen calculates page size from the viewport.
- Archived employees are excluded unless inactive employees are explicitly shown.
- The app sends `show_deleted=true` only when inactive employees are shown; the backend treats `show_deleted` as true only for `1` or `true`.
- Rows are ordered by staff name and then creation time in the repository.
- The linked-user badge is binary: it uses whether `staff.user_id` is present, not a full linked-user lookup.
- Do not document `staff:manage` as a confirmed backend substitute for `staff:view`; the UI may expose management actions, but the list backend checks `staff:view`.
- Role labels can require `staff-roles:view`; without role data, role display and filtering may be incomplete.
Expected result
The operator can review the selected location's active staff, narrow the list locally, and include inactive staff for visibility without creating, editing, deactivating or restoring any record.