Team Management

Team Management is your organization's digital people directory.

If you need to know who has an account in your organization, what their role is, what department they belong to, or whether their account is active, this is where you go. It is the central hub for adding new employees to the platform, managing their profile details, and revoking access when they leave.

Why Team Management Exists

As an organization grows from 5 employees to 50, 500, or more, administrators need one reliable place to manage the people who can participate in the platform.

If user records are unmanaged or scattered, you risk:

• Security vulnerabilities: Former employees might retain active access to sensitive data.
• Operational confusion: Project managers won't know which department an employee belongs to.
• Licensing waste: Inactive accounts might consume paid software licenses unnecessarily.

Team Management prevents these issues by providing a single, tightly controlled interface to oversee every human being connected to your organization.

A Simple Real-World Example

Imagine a new Engineer named Priya joins the company.

Here is how Team Management fits into her onboarding lifecycle:

1. Priya joins the company.
2. The administrator goes to Team Management and clicks Add Member.
3. The administrator types [email protected] and selects the Engineering role.
4. The system immediately sends an invitation email to Priya.
5. Priya's status changes from "invited" to "active" once she signs up.
6. The administrator later opens Priya's Employee Details to log her Employee ID, Emergency Contact, and Department.

The Mental Model

To understand how Team Management works, it helps to see how it connects to the rest of the platform.

• Organization Members: The core list of people on this page.
• User Role Mapping: Team Management lets you assign a role, but the exact permissions of that role are managed in User Role Mapping and Roles & Permissions.
• Departments & Grades: Employees are tagged with departments and grades, which are used later for reporting and cost calculations.
• Profile Details: Additional context like phone numbers and emergency contacts.

---

Understanding the Team Management Page

The Team Management dashboard is divided into several powerful tools designed for scale.

Quick Reference Guide

UI Element	What It Does	When To Use It	Result
License Usage Bar	Shows consumed seats vs total limit	Tracking platform costs	Visual indicator turns red near limit
Search Bar	Finds users by name, email, or ID	When looking for a specific person	Filters the table instantly
Group By	Groups rows by Department, Grade, etc.	When analyzing team sizes	Reorganizes the table into collapsible sections
Filter By	Hides users not matching a criteria	When you only want to see "Engineering"	Table only shows matching users
+ Add Member	Opens the invitation form	Onboarding a new employee	Sends an invite email
Details Button (Gear/User)	Opens the full employee profile	Adding HR/Operational data	Opens the right-side detail drawer
Role Button (Edit)	Changes a user's role	When an employee gets promoted	Overwrites their previous role
Resend Button	Sends the invite email again	If the employee lost the email	Triggers a new email delivery
Remove Button	Deletes the user	When an employee leaves	Permanently removes them from the organization

---

Adding a Team Member

Adding a member sends an automated invitation to their email address, allowing them to join your workspace securely.

Step 1 — Open Team Management

Navigate to Organization Settings → Team Management.

Step 2 — Check Your License Limit

Look at the License Usage bar at the top of the page. You cannot invite new members if you have reached your max_users limit.

Step 3 — Click + Add Member

Click the primary button at the top right. A drawer will slide out.

Step 4 — Enter Member Information

• Full Name: Their actual name.
• Email Address: Their work email. (The system will instantly check if this email is already registered to another active user and warn you).
• Assign Role: Pick the access profile they should receive immediately upon joining.

Step 5 — Send Invitation

Click Send Invitation.

What Happens Next?

The system creates a user record with the status Invited. They will receive an email. Once they click the link and complete registration, their status automatically changes to Active.

---

Employee Details Explained

While you only need a name and email to invite someone, managing a real organization requires more context. Clicking the Details (Gear/User icon) next to any active user opens their full Employee Details form.

Work Information Fields

Field	Required?	What To Enter	Why It Matters
Employee ID	Yes	Unique company identifier (e.g., EMP-042).	Used for payroll and strict identification. Tip: Click the refresh icon to auto-generate the next available ID.
Designation	No	Job title (e.g., Senior Engineer).	Helps others understand this person's responsibilities.
Department	No	Select from predefined departments.	Critical for routing tickets, calculating costs, and team grouping.
Grade/Level	No	Select from expense grades (e.g., L3).	Used to determine expense policies and resource cost profiles.
Cost Center	No	Accounting code (e.g., CC-IN-01).	Used by finance for budget allocation.
Employment Type	No	Full-time, Part-time, Contract, Intern.	Helps distinguish contractors from core employees.
Joining Date	No	Date they started.	Useful for tenure-based logic.
Work Phone	No	Direct line.	Standard contact info.

Emergency Contact Fields

This section allows you to store a name, relationship (e.g., Spouse), and phone number for emergencies. This data is strictly informational.

---

Editing an Existing Team Member

If you need to change a user's role (for example, they were promoted from 'Employee' to 'Manager'), you do not use the Details drawer.

1. Find the user in the list.
2. Click the Role (Edit) icon on the right side of their row.
3. Select the new role from the dropdown.
4. Click Update Role.

What happens? The change is immediate. The user's access across the entire platform will update to reflect their new role.

---

Active vs Invited Status

Users will display one of two primary statuses in the table:

Status	Meaning	Can Access Platform?	Typical Use
Invited	Administrator sent an invite, but the user hasn't registered yet.	No	Waiting for onboarding. You can click 'Resend' to email them again.
Active	User has registered and is part of the organization.	Yes	Normal day-to-day work.

---

Removing a Team Member

When an employee leaves the company, you must remove them to protect your data.

1. Click the Remove (Trash) icon next to their name.
2. A red warning modal will appear.
3. Type confirmation if requested, and click Delete User.

danger

Removing a member is a destructive action. They instantly lose all access to the organization. Depending on platform configuration, they may be unassigned from ongoing projects, and you will free up one license seat.

---

Team Management vs User Role Mapping

It is easy to confuse Team Management with User Role Mapping. They do similar things, but from different perspectives.

Question	Where to Go
I want to invite a brand new employee.	Team Management
I want to see everyone who currently has the "Finance" role.	User Role Mapping
I want to record an employee's emergency contact.	Team Management
I want to see exactly what checkboxes/permissions an employee has.	User Role Mapping
I want to delete an employee who quit.	Team Management

---

Common Scenarios

An Employee Moves to Another Department

If an employee moves from Marketing to Sales:

1. Go to Team Management, click Details, and change their Department to Sales.
2. Go back to the table, click Edit Role, and change their role from Marketing to Sales.

An Administrator Cannot Find a Member

If you invited someone but cannot see them, ensure your search bar is empty and all Filters are set to "None".

An Employee Lost Their Invite Email

Find their name in the list (their status will say Invited). Click the Resend (Refresh) icon in the actions column. The system will dispatch a fresh email immediately.

---

Before You Make Changes (Checklist)

Before editing or removing a member, quickly ask yourself:

• Are you removing the right person? (Verify their email address, not just their first name).
• Are you changing a role? (Remember this affects what they can see immediately).
• Are you changing their Department? (This may affect their manager's reporting dashboards).

---

Troubleshooting

Problem	Possible Reason	What To Check / Do
Add Member button is disabled / greyed out.	License limit reached.	Look at the License Usage bar. You must remove inactive users to free up seats, or upgrade your plan.
Email input turns red when inviting.	Duplicate email.	The system checks the database in real-time. That email is already registered to an active user.
I changed their department, but they still have old permissions.	Department ≠ Role.	Departments are for HR/Reporting. You must also click Edit Role to change their software permissions.
I don't see the 'Details' button on a user.	Missing permissions.	You need the org.users.details.view permission to see HR data. Contact your Organization Owner.

---

Frequently Asked Questions

Can one user have multiple roles?
No. A user has exactly one primary role at a time. If they need mixed permissions, you should create a new hybrid role in Roles & Permissions.

Can I edit someone's email address?
No. Email addresses function as strict identity keys. If an email is wrong, you must remove the invited user and send a new invitation to the correct address.

Does changing a role take effect immediately?
Yes. The next time the user navigates or refreshes, the new permissions apply.

---

Technical Reference — Developers & QA

This section documents the underlying OO-frontend implementation for developers and QA engineers.

Implementation Architecture

• Route: /org/users (Protected by org.users.view permission).
• Main Component: OrgUsers.tsx.
• Child Components: UserDetailDrawer.tsx (HR fields), ConfirmationModal.tsx, MobileActionBar.tsx.
• State Management: Local React state for search (searchQuery), filters (filterField, groupBy), and drawer visibility (isDrawerOpen).
• Email Validation: Debounced checkEmailAvailability fires GET /org/users/check-email on blur/typing to prevent backend 409 errors early.

API Interactions

Action	Method	Endpoint	Trigger	Payload
Load Users & Stats	GET	/org/users	Page mount	None. Returns { users, max_users, total_users }.
Load Departments	GET	/org/departments	Details drawer open	None.
Invite User	POST	/org/users	Add Member save	{ email, full_name, role_id }
Edit User Role	PUT	/org/users?id={id}	Edit Role save	{ role_id }
Resend Invite	POST	/org/users/resend	Resend button click	{ user_id }
Delete User	DELETE	/org/users?id={id}	Trash button confirm	None
Fetch Details	GET	/org/users/details?user_id={id}	Details drawer open	None
Save Details	POST	/org/users/details	Details save	Flat fields + emergency_contact as JSON string.
Auto-Gen ID	GET	/org/users/next-employee-id	Generate ID click	None

User Data Model

The frontend expects a flattened response for the table view:

interface User {
    id: string;
    email: string;
    full_name: string;
    status: string; // 'active' | 'invited'
    role_id?: string;
    role_name?: string;
    department?: string;
    employee_id?: string;
    // ...other operational fields
}

Downstream Impact & Dependencies

• Service Desk SLAs: ServiceDeskSettingsPage.tsx explicitly links SLA routing to the department field populated in the User Details drawer.
• Project Costing: userService.ts and projectService.ts consume /org/users/${userId}/cost-profiles to calculate project burn rates based on the user's assigned Grade/Level.
• Reporting: Analytics pages (e.g., LeadTeamPerformanceReport.tsx) group metrics based on the HR data set in this module.

QA Verification Checklist

• License Limits: Mock max_users to equal total_users. Verify the "+ Add Member" button disables correctly.
• Debounced Email Check: Type a known existing email. Verify the real-time red error message appears and the submit button disables.
• Grouping/Filtering: Verify that grouping by "Department" correctly parses users with null departments into an "Unknown" or default bucket without crashing.
• JSON Payload Serialization: When saving Employee Details, verify via Network tab that emergency_contact is successfully stringified before transport (as expected by backend).
• Drawer Reset: Open 'Add Member', type data, close without saving. Open 'Add Member' again. Verify fields are empty.
• Legacy Department Support: In the Details Drawer, if a user has a text-based department that no longer exists in /org/departments, verify it renders safely as {field.value} (legacy) in the dropdown.

Related Documentation

• User Role Mapping
• Roles & Permissions
• Organization Locations