Antylogic
DemoApp login

399 operational guides

Docs sections
DocsTeam
Device

Delete employee role

Delete an employee role from the selected Harbor Soho location when it has no active employees assigned. The action is permanent, location-scoped and available only to users who can manage employee roles.

In this article

Employee roles are managed inside the selected location. Deleting a role removes only that location's `staff_roles` record and does not affect roles in other locations.

Because deletion is permanent, Antylogic protects roles that are still in use. If active employees are assigned to the role, the server rejects the deletion even if the user reaches the confirmation modal from Role details.

Before you start

  • You are signed in to Harbor Demo Group with Harbor Soho selected as the current location.
  • Your account has `staff-roles:manage` for the active location.
  • The role exists in the current location and can be opened from Employee roles or Role details.
  • The role has no active employees assigned. In the GB documentation runtime, `STAFF_ROLE_BLOCKED_DELETE_ROLE_ID` is assigned and must only be used for the protected error example.

Instructions

  1. 1.

    Open Employee roles

    Open Employees and roles for the active location, then choose Employee roles. Use the table to review role names, descriptions and the Employees column before starting deletion.

  2. 2.

    Check assignments

    If active employees appear on the role, move them to another role first. Archived employees do not block the implemented deletion rule, but active staff assignments do.

  3. 3.

    Start deletion

    For an unassigned role, choose Delete from the row action or open `location/staff/roles/detail/:roleId` and use the destructive Delete button at the bottom of the form.

  4. 4.

    Confirm Delete role

    In the Delete role modal, choose Delete to send `DELETE /api/app/{orgId}/{locationId}/staff-roles/{roleId}` with no payload, or choose Cancel to keep the role unchanged.

  5. 5.

    Review the result

    A successful deletion returns to Employee roles, refreshes the list and shows Role deleted. If the role is still assigned, the app keeps the role and shows the assigned-role error instead.

Validations and limits

  • `staff-roles:manage` is required to see or run Delete; `staff-roles:view` only allows read access.
  • The backend validates the selected organisation and location context, the role id, and that the role belongs to the current location.
  • The delete request has no body and succeeds with `204 No Content` when all checks pass.
  • Before deleting, the backend checks active staff with `IncludeDeleted: false`; active employees assigned through `staff_role_id` block the action.
  • Assigned-role deletion is rejected with `error.staff_role.delete_assigned` and the UI can show `You can't delete a role that is assigned.`
  • A missing, empty, unknown or different-location `roleId` is treated as not found.
  • There is no bulk delete for employee roles, and `/staff-roles` does not accept collection-level `DELETE`.

Expected result

The unassigned employee role is permanently removed from `staff_roles` for Harbor Soho, the Employee roles list refreshes, and assigned roles remain protected from accidental deletion.

Related articles