Settings Guide

Application Administrator Guide

BriefSpec

1. Introduction

The Settings area in BriefSpec is the central configuration hub for Application Administrators. It provides tenant-wide configuration for software hierarchy, shared artifact libraries, project templates, work schedules, role privileges, subscription plans, SSO, notifications, Scribe360 specification documents, AI provider keys, miscellaneous lookups, and related defaults.

This guide covers every card and inline control on the Settings landing page. Cards visible to a user depend on role privileges; some cards are also gated by the tenant subscription plan. Navigation path: Sidebar > Settings > Settings landing page.

2. Accessing Settings

  • Click the Settings icon in the left sidebar to open the Settings landing page.
  • Breadcrumb trail: Home > Settings.
  • Navigable management cards are sorted alphabetically by title.
  • Inline cards at the top of the grid (AI Token Usage, Tenant Timezone, Time Entry Notifications) are configured in place and are not part of the alphabetical card list.

Card visibility and plan gating

  • Most cards are controlled by a privilege key in Role Privileges. If the key is Hidden, the card does not appear.
  • Some cards are additionally gated by plan boolean entitlements. When locked, the card shows a dashed red border and a plan-upgrade tooltip. Enterprise SSO still opens so administrators can preview the locked screen.
  • While plan/role data is loading, cards show a loading state; wait before clicking.
  • AI Key Management is also blocked when AI features are disabled for the tenant.

Landing page layout

  • AI Token Usage — shown when Role Privileges is visible to the current role.
  • Tenant Timezone — org default timezone and date format.
  • Time Entry Notifications — weekly hours reminder rules and eligible projects.
  • Alphabetical management cards (Software Management, Project Artifacts Library, Project Templates, Project Settings, Work Schedule, Role Privileges, Manage Plan, SSO Configuration, Miscellaneous, Notifications, Scribe360 Specification Documents, AI Key Management).

3. Software Management

Software Management is the master catalog for software platforms and their Pillars and Modules/Epics. This catalog drives project scope selection and pillar/epic filtering in Backlog, Defects, Service Requests, and Test Cases, and supports AI-assisted hierarchy generation.

Navigation: Settings > Software Management.

Plan gate: the card uses entitlement software_management. Without it, the card appears plan-locked.

Main Software (Platforms)

  • Software Name — display name used across project modules.
  • Software Type — Platform, Framework, Library, DevOps Tool, Development Tool, or Other.
  • Version — optional release identifier.
  • Status — Active or Inactive. Only Active platforms appear in project scope dropdowns.
  • Description — optional free-text description.

Pillars and Modules/Epics

  • Pillar — high-level functional domain within a platform (for example HCM > Payroll).
  • Module/Epic — functional area within a pillar.
  • Both carry Active/Inactive status. Inactive entries are hidden from project scope and record forms.

Views and tools

  • List View and Grid View.
  • Search and column filters.
  • Export Software Hierarchy (Excel).
  • Import Software Hierarchy (Excel) with create/skip summary.
  • Generate Pillars and Epics with AI (requires tenant AI features).
  • Add Software / Add Pillar for manual entry.

Business Processes

Each platform can include L1 and L2 Business Processes used by AI-assisted user story and test script generation workflows. Entries support Active/Inactive status and description.

Access control

  • Privilege key: settings-software-management.
  • Plan entitlement: software_management.
  • Hidden = card not shown. Read = view only. Read and Edit = full CRUD.

4. Project Artifacts Library

Project Artifacts Library is the Settings hub for shared, reusable project artifacts. It replaced the former single Testcase Library card on the Settings landing page.

Navigation: Settings > Project Artifacts Library.

Privilege key remains settings-testcase-library. The hub itself opens for authorized roles; individual libraries that require the plan entitlement are marked PLAN when test_case_library_module is off.

Libraries in the hub

  • Test Case Library — store and reuse test cases across projects (plan-gated).
  • User Story Library — store and reuse user stories across projects (plan-gated).
  • RTM Library — store and reuse RTM requirements across projects (plan-gated).
  • Execution Plan Library — store and reuse execution plans (available without the same plan lock as the other three).

Using a library

  • Open a library card from the hub to browse, search, and open detail records.
  • From a project workspace, authorized users can import library items into the matching project module (for example Import from Master Test Cases on the Test Cases tab).
  • Import flows confirm analysis before creating project records.

Access control

  • Privilege key: settings-testcase-library (controls the Project Artifacts Library card).
  • Plan entitlement: test_case_library_module (locks Test Case / User Story / RTM libraries when inactive).

5. Project Templates

Project Templates (Module Configuration Templates) define which modules are active in a project, how record forms are laid out, which workflow statuses are available, and which special feature toggles are enabled. Every project must be assigned a template at creation time.

Navigation: Settings > Project Templates.

Template types

  • System Templates — platform-provided blueprints (for example RTM – All Modules, US – All Modules, Managed Services, Testing, Documentation). Browse and clone; do not edit system originals.
  • Custom Templates (global) — tenant-owned, created by cloning. Editable in Draft; Published locks the template name.
  • Project-scoped templates — Draft copies created when a project is saved with a template selection, typically named {Project ID} – {Source Template Name}.

Key configuration areas

  • Modules — toggle modules on/off subject to dependency rules.
  • Fields — system fields (locked) plus Custom Layout custom fields (Text, Text Area, Number, Currency, Date, Date Time, Dropdown, Multi-select, Checkbox, Email, URL, Phone).
  • Status — workflow statuses for modules that support status.
  • Special Fields — module toggles such as mandatory defect creation, requirement form type (RTM vs User Story), mandatory requirement link for test cases, and mandatory attestation on test cycles.

Lifecycle

  • Draft — full structural editing.
  • Published — name locked; global templates may still allow structural edits; project-scoped Published templates are fully locked.
  • Active / Inactive — Active Published global templates appear in project creation.
  • Promote to Global — converts a project-scoped template into a new global Draft custom template.

Access control

  • Privilege key: settings-project-template.
  • Sub-keys: project-template-view, project-template-add, project-template-update, project-template-delete.

6. Project Settings

Project Settings provides tenant-wide catalogs used when creating and classifying projects. The page is organized as tabs for Project Type and Solution Type.

Navigation: Settings > Project Settings.

Project Type

  • Create, edit, and deactivate project types used in project creation.
  • System-provided types (for example Managed Services, Testing, Documentation) remain available.
  • Custom types support tenant-specific engagement categories.

Solution Type

  • Create, edit, and deactivate solution types tagged to projects for categorization and reporting.
  • Solution types appear in the project creation wizard.

Note: Project Type and Solution Type are managed here. They are not shown as tabs under Miscellaneous (those Misc tabs are hidden in the current product).

Access control

  • Privilege key: settings-project-settings.
  • Tab visibility can also depend on finer privileges for project type / solution type.

7. Work Schedule

Work Schedule defines named business-hour templates and holiday lists for the tenant. Users can inherit the tenant default, pick another template, or enter custom hours.

Navigation: Settings > Work Schedule.

  • Hours templates — named week patterns (for example Mon–Fri 8h / 40h) with a default flag.
  • Holiday lists — named calendars (US, India, UK, or custom) with holiday dates and a default list.
  • Hours per week rolls up from the selected template days.

This card currently has no separate Settings privilege key in the landing card definition; access follows Settings navigation availability for roles that can open Settings.

8. Role Privileges

Role Privileges is the access control center for the tenant. It defines what each role can see and do across Settings cards, project actions, and workspace modules.

Navigation: Settings > Role Privileges.

Roles

  • Named groups such as Application Admin, Project Manager, Author, Tester, Client User.
  • The Tenant role is built-in and cannot be deleted.
  • Create custom roles, clone existing roles, rename, set Active/Inactive, and Reset to Default.

Privilege levels

  • Hidden — feature/UI not visible.
  • Read Only (Read) — visible; create/edit/delete disabled.
  • Read and Edit — full access.

Scope levels

  • All — access all records regardless of ownership.
  • Own — only records created by or assigned to the user.

Settings privilege keys (current)

  • settings-software-management
  • settings-testcase-library (Project Artifacts Library card)
  • settings-project-template (+ project-template-view/add/update/delete)
  • settings-project-settings
  • settings-role-privileges
  • settings-manage-subscription-plan
  • settings-enterprise-sso
  • settings-miscellaneous
  • settings-scribe360-specification-documents
  • settings-openai-key (AI Key Management card)

Access control

  • Privilege key: settings-role-privileges.
  • Restrict to Tenant Administrators and authorized Application Admins.

9. Manage Plan

Manage Plan is where authorized billing contacts review the active subscription, entitlements, utilization quotas, plan changes, and add-on purchases (including AI token top-ups).

Navigation: Settings > Manage Plan.

  • Review current plan tier and feature entitlements.
  • Monitor utilization metrics (projects, templates, custom fields, seats, AI tokens, and other plan limits).
  • Purchase or change plans via Stripe checkout where enabled.
  • Purchase add-ons such as AI token packs when approaching plan_token_limit.

Access control

  • Privilege key: settings-manage-subscription-plan.
  • Typical: Read and Edit for Tenant Admins / billing contacts; Hidden for project-only roles.

10. SSO Configuration

SSO Configuration connects BriefSpec to the organization’s identity provider using OpenID Connect (OIDC). Enterprise SSO lets users with verified company email domains sign in through Microsoft Entra, Okta, or a generic OIDC provider.

Navigation: Settings > SSO Configuration.

Plan gate: enterprise_sso. When the plan does not include Enterprise SSO, the card is locked but the screen can still be opened to preview requirements.

What it controls

  • Connection status — draft, testing, active, disabled, or error; last test and last updated.
  • Provider settings — display name, preset (Microsoft Entra, Okta, Generic OIDC), issuer URL, discovery URL, client ID, optional email fallback claim, account prompt.
  • Provider callback URL — Redirect URI / Reply URL to register in the IdP.
  • Client secret — stored encrypted; only a masked hint is shown after save.
  • Verified domains — add domains, publish DNS TXT, verify ownership before activation.
  • Test and activation — test connection, then activate or disable.

Important behaviors

  • Enterprise SSO signs in existing BriefSpec users only. It does not auto-create users or tenants.
  • Users must already exist with an email on a verified domain.
  • Use the information icon for OIDC setup instructions (Entra/Okta samples and domain verification steps).

Access control

  • Privilege key: settings-enterprise-sso.
  • Plan entitlement: enterprise_sso.

11. Miscellaneous

Miscellaneous is a multi-tab panel for tenant-wide lookup data used on records, reporting, branding, personas, functional roles, and requirement sizing.

Navigation: Settings > Miscellaneous.

Tabs

  • Industry — industries for clients/projects.
  • Department — internal departments.
  • Location — office/delivery locations.
  • Currency — currency catalog.
  • Company Size — size bands with display order.
  • Revenue — revenue bands/lookups.
  • Resource Rate — rate definitions for effort cost calculations.
  • Designation — job title classifications.
  • Branding — white-label / branding options (privilege-gated).
  • Persona — personas used on projects (privilege-gated).
  • Functional Roles — functional role catalog (privilege-gated).
  • Requirement Sizing — sizing lookups (privilege-gated).

Project Type and Solution Type tabs exist in code but are hidden in Miscellaneous; manage those under Project Settings.

Common operations

  • Add, inline edit, Active/Inactive toggle, delete (blocked when referenced), search, Active/Inactive filter.
  • Name uniqueness within a category; Company Size display order must be a unique positive number.

Access control

  • Privilege key: settings-miscellaneous.
  • Individual tabs also use finer keys (for example miscellaneous-view-persona, miscellaneous-view-functional-role).

12. Notifications

Notifications configures tenant rules for in-app (and related) reminders across Test Cycles, Service Requests, Defects, and Phases — including calendar offsets, pace checkpoints, escalations, and recipient roles.

Navigation: Settings > Notifications.

Areas

  • Test Cycle — calendar day-offset reminders and pace checkpoints (elapsed % vs completion threshold) with recipients such as tester, project manager, cycle owner.
  • Service Requests — calendar offsets, priority/severity escalations, and closed/reopened notifications.
  • Defects — calendar offsets and recipient sets (assignee, creator, project manager).
  • Phase — phase-oriented notification rules.

This Settings card is not gated by a separate settings-* privilege key on the landing card; treat it as an App Admin configuration surface and confirm role access during rollout.

13. Scribe360 Specification Documents

Scribe360 Specification Documents stores Reports and Integrations specification files used by Scribe360. Administrators upload, organize in folders, version/replace files, tag, link to scope, and track embedding/index status.

Navigation: Settings > Scribe360 Specification Documents.

  • Two document type workspaces: Reports and Integrations.
  • Folder tree with nested folders (depth limited).
  • Upload with accepted document types and max file size enforced by the API.
  • Replace/version files, move, bulk link/move, activity history, and embedding retry when indexing fails.

Access control

  • Privilege key: settings-scribe360-specification-documents.

14. AI Key Management

AI Key Management (formerly OpenAI Key) lets a tenant store its own AI provider API configuration in AWS Secrets Manager, overriding the platform default for AI-powered features.

Navigation: Settings > AI Key Management.

Plan gate: configure_own_openai_key. The card also requires tenant AI features to be enabled.

Configuration

  • API provider — OpenAI or Claude AI.
  • API key — paste and save; status shows configured source and masked hint.
  • Model — provider-specific model catalog.
  • Reasoning effort — allowed efforts depend on provider/model (for example low, medium, high, xhigh, max).
  • Delete Tenant-Specific Key — revert to platform default.
  • Refresh Key Status — reload without full page reload.

Impact

  • When a tenant key is active, AI-assisted generation routes through that provider configuration.
  • Platform AI Token Usage still reports tenant consumption against plan_token_limit / wallet allowances.

Access control

  • Privilege key: settings-openai-key.
  • Plan entitlement: configure_own_openai_key.

15. AI Token Usage

The AI Token Usage widget appears at the top of the Settings landing page when the Role Privileges feature is visible to the current role. It summarizes token consumption versus allocated allowance for the plan period, with refresh and export actions where enabled.

  • Usage tokens consumed in the current plan period.
  • Total / included allowance from plan entitlements or AI token wallet.
  • Plan period dates when available.
  • Refresh to reload latest figures; export may be available for detailed usage.

If usage approaches the limit, purchase an add-on via Settings > Manage Plan or contact BriefSpec. A tenant-specific AI key does not remove the need to monitor this widget for plan allowance.

16. Tenant Timezone

Tenant Timezone is an inline Settings card that sets the organization default timezone and date format used across the app.

  • Select a timezone and optional date format metadata.
  • Save updates the tenant default; user settings refresh after save.
  • Empty state prompts when no timezone/format is selected yet.
  •  

17. Time Entry Notifications

Time Entry Notifications is an inline Settings card for weekly logged-hours reminder rules. It controls whether notifications run, who is notified, which weekday the check uses, the minimum weekly hours threshold, and which projects are included.

  • Enable / disable the notification job.
  • Notify users and/or project managers.
  • Weekday for the weekly check.
  • Minimum weekly logged hours (1–168 in 0.25 steps; default 40.00).
  • Select eligible time-entry projects to include.

18. Role-Based Access Reference

Every Settings management card below is governed by a privilege key in Settings > Role Privileges (unless noted).

  • settings-software-management — Software Management (also plan: software_management).
  • settings-testcase-library — Project Artifacts Library card (libraries also plan: test_case_library_module).
  • settings-project-template — Project Templates (+ view/add/update/delete sub-keys).
  • settings-project-settings — Project Settings.
  • settings-role-privileges — Role Privileges.
  • settings-manage-subscription-plan — Manage Plan.
  • settings-enterprise-sso — SSO Configuration (also plan: enterprise_sso).
  • settings-miscellaneous — Miscellaneous.
  • settings-scribe360-specification-documents — Scribe360 Specification Documents.
  • settings-openai-key — AI Key Management (also plan: configure_own_openai_key; requires tenant AI enabled).
  • Work Schedule / Notifications / Tenant Timezone / Time Entry Notifications — configure via Settings; confirm role access during rollout (landing cards may not use a dedicated settings-* key).

19. Common Messages and Troubleshooting

  • You do not have permission to view this screen — missing Settings privilege; ask a Tenant Administrator to update Role Privileges.
  • To access this feature, please upgrade your plan — plan boolean entitlement is off (Software Management, Project Artifacts libraries, AI Key, Enterprise SSO, etc.).
  • To access this feature, please upgrade your plan to Enterprise — Enterprise SSO plan lock tooltip.
  • AI-powered features are currently disabled for this tenant — tenant AI flag off; AI Key Management stays locked.
  • Loading your plan and role access. Please wait — wait for privilege/plan load before clicking cards.
  • Unable to load Stripe billing catalog — temporary Manage Plan pricing error; refresh or contact support.
  • Failed to save AI key / secret store errors — verify key format and contact support if Secrets Manager storage fails.
  • Lookup is in use — Miscellaneous entry referenced by live records; set Inactive instead of deleting.

20. Recommended Practices

  • Configure Software Management before creating projects that need pillars/epics in scope.
  • Set Role Privileges early; limit Edit on Role Privileges, Manage Plan, SSO, and AI Key Management.
  • Use Project Artifacts Library for reusable test cases, stories, RTM, and execution plans instead of re-entering content.
  • Publish Project Templates only when validated; clone Published templates to Draft for structural changes.
  • Set Tenant Timezone and Work Schedule before rolling out time entry and financial planning.
  • Configure Notifications and Time Entry Notifications with project managers before go-live.
  • Monitor AI Token Usage and Manage Plan utilization monthly.
  • For Scribe360, keep Specification Documents organized (Reports vs Integrations) and verify embedding status after uploads.
  • Prefer Inactive over Delete for lookup data that appears on historical records.

Appendix A: Settings Card Summary

  • AI Token Usage (widget) — plan period token consumption.
  • Tenant Timezone — org timezone and date format.
  • Time Entry Notifications — weekly hours reminder rules.
  • AI Key Management — provider/model/effort + API key. Privilege: settings-openai-key. Plan: configure_own_openai_key.
  • Manage Plan — subscription and utilization. Privilege: settings-manage-subscription-plan.
  • Miscellaneous — lookups, branding, personas, functional roles, requirement sizing. Privilege: settings-miscellaneous.
  • Notifications — test cycle / SR / defect / phase rules.
  • Project Artifacts Library — shared libraries hub. Privilege: settings-testcase-library.
  • Project Settings — project type and solution type. Privilege: settings-project-settings.
  • Project Templates — module configuration templates. Privilege: settings-project-template.
  • Role Privileges — role access control. Privilege: settings-role-privileges.
  • Scribe360 Specification Documents — Reports/Integrations repository. Privilege: settings-scribe360-specification-documents.
  • Software Management — platforms, pillars, epics, business processes. Privilege: settings-software-management. Plan: software_management.
  • SSO Configuration — Enterprise OIDC. Privilege: settings-enterprise-sso. Plan: enterprise_sso.
  • Work Schedule — hours templates and holiday lists.

Appendix B: First-Time Setup Checklist for App Admins

  • 1. Configure Role Privileges for all intended roles.
  • 2. Set Tenant Timezone and Work Schedule.
  • 3. Configure Software Management (platforms, pillars, modules/epics).
  • 4. Configure Miscellaneous lookups (Industry, Department, Location, Currency, Company Size, etc.).
  • 5. Configure Project Type and Solution Type in Project Settings.
  • 6. Create or review Project Templates.
  • 7. Review Manage Plan limits before onboarding users and projects.
  • 8. Configure AI Key Management if the tenant needs a dedicated provider key.
  • 9. Configure Notifications and Time Entry Notifications.
  • 10. Optionally seed Project Artifacts Library and Scribe360 Specification Documents.
  • 11. Add users/roles, then create initial projects.
  • 12. Configure SSO when the plan includes Enterprise SSO.

Appendix C: Related Settings Cross-Reference

  • Project Type / Solution Type — Settings > Project Settings (not Miscellaneous).
  • Project Templates — Settings > Project Templates; also referenced from project create/edit.
  • Role Privileges — global; changes apply immediately.
  • Software Management pillars/epics — used in project creation, Backlog, Defects, Service Requests, Test Cases, and AI generation.
  • Plan limits — Settings > Manage Plan; enforced across projects, templates, fields, seats, and AI tokens.
  • AI Key Management — affects all AI features; monitor AI Token Usage for plan allowance.
  •