Admin Guide

Application Administrator Guide

BriefSpec

1. Introduction

Welcome to the BriefSpec Admin Guide. This guide helps Application Administrators (and other roles granted the same privileges) perform the core setup activities that unlock day-to-day use of the product: creating Clients and Client Users, and creating internal tenant Users.

Clients represent customer organizations. Client Users are people from those organizations who collaborate in project workspaces. Tenant Users are your internal team members (for example Application Admin, Author, Project Manager, Tester).

What this guide covers

Creating and editing Clients (Basic Details, Additional Info, Billing).

Adding Client Users and choosing Client Reviewer / Client Tester / Client User roles.

Managing tenant Users (list, add/edit, import/export, plan seat limits).

Users page tabs: Users, Team (Org Teams), and Resume Library.

System role meanings and how privileges actually control access.

Related guides

Settings Guide — Software Management, Project Templates, Role Privileges, Manage Plan, SSO, and other tenant configuration.

Using Smart Merge — AI duplicate cleanup on the Backlog (privilege- and plan-gated).

2. Who can perform these tasks

Access is controlled by Role Privileges and plan entitlements — not by role name alone. Application Admin typically has full access, but a custom role can be granted the same privileges.

Clients

Screen privilege: view-client (sidebar Clients).

Actions: add-client, update-client, delete-client, export-clients.

Client Users: add-client-users, edit-client-user, delete-client-user.

Users

Screen privilege: users-view (Users tab).

Actions: add-users, update-users, delete-users, import-users, export-users.

Resume Library tab: users-resume-indexing.

Team tab (Org Teams): requires plan entitlement team_management (when enabled for the tenant).

Plan seat limits

Active internal users and active client users are limited by the subscription plan. When a limit is reached, Add / Import actions may be disabled with an upgrade or quota message. Review Settings > Manage Plan for current utilization.

3. Setting up Clients and Client Users

3.1 Open Clients

In the left sidebar, click Clients. The Clients list shows organizations already configured for the tenant.

You will see the Clients list screen.

On a brand-new tenant the list may be empty. Use the + (Add) control to create the first Client.

3.2 Add a Client

The Client form is organized into sections. Fields marked with * are mandatory for save.

Sections:

Basic Details (required to create) — at minimum Client Name, contact First Name, Last Name, and Contact Email.

Additional Info (optional) — industry, company size, and related profile fields when available.

Billing (optional) — billing contact, billing email, and billing address.

Click Save to create the Client. After a successful save, the Client Users tab becomes available so you can invite people from that organization.

3.3 Add Client Users

Open the Client Users tab on the Client record. If none exist yet, the list is empty.

Click + to add a Client User.

Enter the Client User details on the form.

First Name, Last Name, Email, and Role are required. Choose a Client role that matches how the person will participate in projects.

3.4 Client roles

BriefSpec supports these primary Client roles:

Client Reviewer — formal review and sign-off. Can review backlog items and, where your process uses it, approve or reject them; participates in review assignment on phase work; has stakeholder read access so decisions are informed. Assign to contacts accountable for acceptance or business approval.

Client Tester — invited to run tests (for example client UAT). Oriented to test execution and outcomes — assigned test lists, execution progress, and defects — rather than backlog planning or approval. Use when you need client-side executors without full planning/approval duties.

Client User — default stakeholder role. Views project details and related artifacts for visibility and light collaboration. Not the primary role for formal backlog approval (Client Reviewer) or hands-on execution assignments (Client Tester).

Exact screens and actions for each role still depend on Role Privileges configured under Settings > Role Privileges. Treat the descriptions above as the intended product posture.

4. Managing Users

Users is where administrators manage internal tenant accounts — listing people, adding users, updating roles and access, importing/exporting, and (when enabled) managing Org Teams and the Resume Library.

4.1 Users page tabs

Users — primary list of tenant users; add, edit, deactivate/delete (per privilege), import, and export.

Team — Org Teams: named groups of internal users with members and aliases (plan: team_management). Separate from project Team Members inside a project workspace.

Resume Library — skills/resume indexing for resource matching (privilege: users-resume-indexing).

4.2 Open Users and add a user

In the left sidebar, click Users.

The Users list appears (it may be empty on a new tenant).

Click + to add a user. Complete the form sections and click Save.

Typical Add/Edit User sections:

Details — name, email (often domain-whitelisted), role, location, and related profile fields.

Billing — cost/bill rates and effective dates when financial planning is in use.

Work Schedule — inherit tenant default hours/holidays or select a template / custom hours.

Workload (edit) — project assignments overview when available.

Import and Export actions may appear on the Users toolbar when privileges and plan allow. If the internal-user seat limit is reached, Add and Import stay disabled until seats are freed or the plan is upgraded.

4.3 System roles (internal)

The Role dropdown lists system roles and any custom roles created under Settings > Role Privileges. Common system roles:

Application Admin — full tenant administrator (aligned with legacy Test Admin in the product). Can manage users, clients, settings, and global configuration. Assign sparingly.

Author — backlog and delivery contributor. Views backlog requirements; updates are typically limited to assigned items. Works assigned requirements in Phase; can generate test cases and execute assigned tests in a Test Cycle when privileges allow. (This is the product role name — not “Developer.”)

Project Manager — senior delivery role for clients, projects, and workspace execution (Backlog, Phase, Test Cases, Test Cycles) when privileges grant those screens. Settings and libraries are available only if Role Privileges and plan entitlements allow — do not assume every PM has full Settings access.

Tester — focused on running tests and recording outcomes. Execution-oriented; broader project-admin navigation is usually restricted for separation of duties.

Custom roles can clone any of the above. Always verify Settings > Role Privileges for the exact feature keys granted to a role before promising access in training materials.

4.4 Org Teams (Users > Team)

Org Teams (Users > Team) are tenant-wide groups of internal users. Each team has a name, an email alias (letters, numbers, and hyphens only), Active/Inactive status, and a member list. The page intent is to create teams, manage members, and send mail to the team alias.

Where it is used

Users > Team — create and maintain teams, add/remove members, set Active/Inactive, and view associated projects returned by the API.

Project Financial Plan — when a plan task’s owner mode is Team, you pick an active Org Team. Eligible members are pulled onto the task for budgeting (hours/cost/revenue).

Email — mail can be sent to the team alias address so the group is reachable without listing every member.

How to use it

Open Users > Team (requires plan entitlement team_management).

Create a team with Name + Alias, set status, and add internal tenant users as members.

In a project Financial Plan, set a task owner to Team, select the Org Team, and resolve any member blockers before saving.

Restrictions

Plan gate: Team tab is unavailable unless team_management is on the subscription.

Privileges: viewing Users (users-view) is required; creating teams uses add-users; editing uses update-users (same keys as user management).

Org Teams are not project Team Members. Adding someone to an Org Team does not automatically add them to a project.

Financial Plan team ownership only lists Active teams. Members must be Active on the team, must not be Client roles, must already be on that project, and must have both bill and cost rates set — otherwise the UI blocks the assignment with fix-up messages.

Alias must use letters, numbers, and hyphens only (stored lowercase).

4.5 Resume Library

The Resume Library tab supports indexing user resumes/skills for matching. Visibility requires privilege users-resume-indexing. Some administrators see only this tab when they lack users-view.

5. Recommended practices

Create at least one Client before creating client-linked projects.

Add Application Admin and Project Manager users early; grant Author/Tester as delivery ramps up.

Use Client Reviewer only for people who will approve work; use Client Tester for UAT executors.

Keep Role Privileges reviewed after every custom-role change.

Watch Manage Plan seat utilization before large user imports.

Prefer Org Teams for reusable staffing groups; use project Team Members for project-specific assignment.

Configure Software Management and Project Templates (Settings Guide) before bulk project creation.

6. Common messages and troubleshooting

Clients / Users missing from the sidebar — privilege view-client or users-view is Hidden for the role.

Cannot add Client or User — missing add-client / add-users privilege, or plan seat quota reached.

Client Users tab disabled — save the Client first; confirm add-client-users privilege.

Team tab missing — plan team_management inactive or Users screen privilege insufficient.

Resume Library missing — users-resume-indexing is Hidden.

Email rejected — address must match tenant email domain whitelist / alias policy.

User cannot see Settings cards — grant the matching settings-* privileges (see Settings Guide).

Appendix A: Privilege key quick reference

Clients: view-client, add-client, update-client, delete-client, export-clients, add-client-users, edit-client-user, delete-client-user.

Users: users-view, add-users, update-users, delete-users, import-users, export-users, users-resume-indexing.

Plan: no_of_active_* user seat limits; team_management for Org Teams.

Appendix B: First-time admin checklist

1. Confirm your role can open Clients, Users, and Settings.

2. Create the first Client (Basic Details at minimum).

3. Add Client Users with the correct Client roles.

4. Add internal Users (Application Admin already exists; add PM / Author / Tester as needed).

5. Optional: create Org Teams; configure Resume Library if used.

6. Continue in Settings Guide: Software Management, templates, Role Privileges, Manage Plan.

7. Create the first Project and invite the right users.