Create staff member

In this article

Before you start

• You are signed in with an active organisation and location selected; in the GB demo runtime this is Harbor Demo Group and Harbor Soho.
• At least one staff role exists for Harbor Soho and is visible to the form.
• Your account has staff:manage for the active location.
• To link an existing user, your account can view or manage location users and an accepted user exists without an existing staff record.
• To create an internal user from the form, your account has users:manage.

Instructions

1. 1.

   Open Employees

   Open Employees and roles for Harbor Soho and stay on the Employees tab. When staff management is allowed, the staff table header shows Register.

2. 2.

   Start registration

   Select Register to open Register employee. The form loads employee roles and, when user permissions allow it, accepted location users that are not already linked to staff.

3. 3.

   Choose a role

   Select the employee role that classifies the staff member operationally. The form may select the first available role automatically, but the record still needs a valid staff_role_id before it can be saved.

4. 4.

   Add identity details

   For a manual employee, enter first name and last name, then add email, phone and avatar if useful. To reuse an existing platform profile, select an accepted user and enable Use user data so the staff record inherits the user's name, contact details and avatar.

5. 5.

   Set annual leave

   Enter the annual vacation allowance. On create, Prorate annual vacation days starts enabled so Antylogic can create an accepted fictional vacation event for the elapsed part of the year when the calculated value is greater than zero.

6. 6.

   Register the employee

   Submit the form. Antylogic creates the staff record in the current Harbor Soho location, refreshes staff, user and calendar-related data, shows the success state and returns to the Employees tab.

Validations and limits

• staff:manage is required to open the create screen and to submit POST /api/app/{orgId}/{locationId}/staff.
• The screen needs a selected organisation and location; missing context is shown as an error state.
• staff_role_id is required. The backend rejects an empty role and repository tests cover missing-role and foreign-role failures.
• Without a linked user, the UI requires first name and last name before submission.
• When Use user data is enabled with a selected user, manual identity, contact and avatar fields are disabled and the backend overwrites those fields from the user profile.
• Annual leave is normalised in the UI to a whole number with a minimum of 0; the creation-only proration flag is not part of later employee edits.
• Invalid JSON on POST /staff returns HTTP 400, and failed API submission keeps the form open with an error message.
• The role selector depends on GET /staff-roles. A permission set with staff:manage but without staff-roles:view can block role loading even though the create POST itself requires staff:manage.
• No verified backend evidence was found for email format, phone format, full-name uniqueness or a backend maximum annual-leave validation in this action.

Expected result

The staff member is created for Harbor Soho with the selected employee role. If user data is used, the employee identity is inherited from that user; if leave proration applies, a fictional accepted vacation event can be created for the elapsed part of the year.