Filter employees
Narrow the Employees table for the active location by search text, employee role, inactive-employee visibility and page without changing employee records.
In this article
Use the Employees tab to focus the staff list for the selected location before service. In the GB demo, the guide is grounded in Harbor Demo Group and the Harbor Soho location, with visible staff such as Olivia Hart, Mason Reed, Noah Stone and Ava Price.
Search, role selection and pagination are local table filters. Show inactive employees is the only control in this action that changes the staff list request, because it asks the backend to include archived employee records.
Before you start
- You are signed in with an organisation and location selected, such as Harbor Demo Group and Harbor Soho.
- Open Employees and roles on the Employees tab with `location/staff?tab=staff`.
- Your account can view employees for the location. Employee role names and filter options require access to employee roles.
- The employee list for the active location can load; role filtering needs the employee role catalogue to load as well.
Instructions
- 1.
Open Employees
Open Employees and roles and select Employees. The default view shows active employees only, with the search field, Employee role selector, table pagination and Show inactive employees control.
- 2.
Search employees
Type a name, email, phone number or role text in Search by name, email, or role. The screen trims the text, applies it after a short delay, resets `staff_page` to 1 and filters the already loaded rows. In the GB demo, `staff_query=Olivia` finds Olivia Hart.
- 3.
Filter by role
Choose one Employee role to show only employees whose `staff_role_id` matches that role. Choose All to clear the role filter and return to every role in the current active-location list.
- 4.
Show inactive employees
Turn on Show inactive employees to include archived staff. The screen requests `show_deleted=true`, then shows active and inactive rows together and adds the Status column.
- 5.
Change page
Use the table pagination controls to move through the filtered rows. Pagination stays local to the current table view; the staff endpoint is not called with page or page size.
Validations and limits
- The action is read-only: it changes route filters and table state, but it does not create, edit, deactivate, restore or delete employees.
- Search is case-insensitive and checks employee name, email, phone and resolved employee role name.
- Blank search text is removed as an active filter. Invalid, zero or negative `staff_page` values fall back to page 1.
- The role filter compares the selected id with each employee record's `staff_role_id`; if the selected role id is missing after roles load, the screen clears the role filter and returns to page 1.
- Only `show_deleted=true` is sent to `GET /api/app/{orgId}/{locationId}/staff`; `staff_query`, `staff_role_id` and `staff_page` are applied in the UI.
- The staff list endpoint requires `staff:view`. The UI can treat `staff:manage` as visual access, but the backend list action still checks `staff:view`.
- The role selector depends on the employee role catalogue and `staff-roles:view`; without it, operators may only see All and role-name search matches are unavailable.
- `staff_page_size` is parsed in the route configuration, but this screen estimates page size from the viewport.
Expected result
The employee table is narrowed to the current search, role, inactive-visibility and page state while employee records remain unchanged.