Antylogic
DemoApp login

399 operational guides

Docs sections
DocsStaff
Device

How to create an employee role

Create a location-scoped employee role for Harbor Soho with a required name, optional description and selected colour. The action adds the role to staff_roles; it does not assign employees.

In this article

Employee roles keep the local staff list organised around the work people actually do in a venue. For Harbor Soho, a manager can add a temporary role such as Private Events before a private tasting evening and keep it separate from the base floor, kitchen and bar roles.

The flow starts from Staff management in the active location. Antylogic checks the location permission, opens the Create employee role form, saves the role for the current location and then returns to Employee roles with the refreshed list.

Before you start

  • Sign in to Harbor Demo Group with Harbor Soho selected as the active location.
  • Use the location-scoped Staff management routes: `location/staff?tab=roles` or `location/staff/roles/create?tab=roles`.
  • The user needs `staff-roles:manage` for Harbor Soho. Users with only `staff-roles:view` can see roles but cannot create one.
  • Choose a role name that is unique within Harbor Soho, such as `Private Events`, and remove temporary documentation roles after capture.

Instructions

  1. 1.

    Open Employee roles

    Open Staff management for Harbor Soho and switch to `Employee roles`. The tab shows existing role rows, search by name or description, role columns and the `Create role` action when the user can manage roles.

  2. 2.

    Start a new role

    Select `Create role`. Antylogic opens `Create employee role` with fields for `Name`, `Description` and `Color`. If the user lacks `staff-roles:manage`, the create screen shows a no-access state instead of the form.

  3. 3.

    Enter the role details

    Fill in a clear role name. For the Harbor Soho example, use `Private Events` with the optional description `Supports Harbor Soho private tasting evening service`. Empty description text is treated as no description.

  4. 4.

    Choose a colour

    Select one of the predefined colour swatches, such as `Indigo` or `Purple`, so the role is easy to recognise in staff screens. The form does not allow free-text or hex colour entry.

  5. 5.

    Create the role

    When `Name` and `Color` are complete, select `Create role`. The save sends the trimmed name, optional description and selected colour to `POST /api/app/{orgId}/{locationId}/staff-roles` for the active Harbor Soho location.

  6. 6.

    Confirm the result

    After success, the app shows `Role created`, returns to `Employee roles` and reloads the list. Confirm the new role appears there, normally with no employees assigned yet.

  7. 7.

    Cancel without saving

    Use `Cancel` or go back from the form when the role should not be created. The app returns to Staff management on the roles tab without calling the create action.

Validations and limits

  • `selectedOrgId` and `selectedLocationId` must be present before the create form can render.
  • `staff-roles:manage` is required in the UI and by the location API endpoint.
  • `Name` is required after trimming whitespace and must be unique within the same location.
  • `Color` is required by the UI and must come from the predefined swatches: gray, blue, indigo, purple, pink, orange, success, warning and error.
  • `Description` is optional; whitespace-only values are omitted from the create payload.
  • The role belongs only to the active location. Creating it does not create employees or assign existing staff to the role.
  • If the request fails, the user stays on the form and sees the resolved API or network error.

Expected result

Harbor Soho gets a new local employee role in `staff_roles`, visible in Employee roles after the list reloads and ready to use later from staff profiles or related staff flows.

Related articles