15.1 When Setup Runs
Setup is required when any of the 18 required SharePoint lists are missing or incomplete. The app shows a Setup required banner until provisioning completes. Only a site collection owner (Full Control) can run setup. App administrators can view Settings → Setup status but cannot provision lists without site owner permission.
- First visit after deploying the web part — modal or full-page setup wizard
- Setup required banner — Complete Setup button (site owner only)
- Settings → Setup status — Complete Setup or Refresh
- Sidebar Complete Setup link when lists are incomplete
Publish the SharePoint page before running setup. The wizard does not run while the page is in edit mode.
15.2 Setup Wizard — Pre-Start Screen
Before you click Start Setup, the wizard shows what the app provides and an optional sample data checkbox.
| Control | Description |
|---|---|
| Start Setup | Begins provisioning with the sample data checkbox state below |
| Skip (lists already exist) | Dismisses the wizard when lists are already present |
| Add sample data | Optional checkbox — see section 15.4 |
| Close (X) | Dismisses the modal when not running (modal variant only) |
Feature highlights (informational)
- Time tracking & approvals — log hours and route timesheets through approval workflows
- Projects & billing — clients, projects, rates, and invoices
- Expenses & PTO — expense reports, paid time off, and holidays
- Reports & analytics — utilization, billing, and team dashboards
- Team management — departments, teams, roles, and permissions
- Settings & templates — email templates, tax profiles, and app configuration
15.3 Provisioning Steps (in order)
| Step | Label | What happens |
|---|---|---|
| check | Checking permissions and existing lists | Verifies site owner access and detects existing lists |
| org | Creating organization lists | UserRoles, Employees, Departments, Teams, RolePermissions |
| timesheets | Creating timesheet lists | Periods, Timesheets, TimeEntries, TimesheetApprovals, Holidays, PTORequests, ExpenseCategories, Expenses |
| billing | Creating billing lists | TaxProfiles, Clients, Projects, Tasks, Rates, Invoices, InvoiceLines, Retainers, Payments |
| settings | Creating settings lists | AppSettings, EmailTemplates, InvoiceTemplates, CustomFields, CustomFieldValues, UserSettings, AuditLogs, TimesheetDocuments library |
| seed | Seeding sample data (optional) | Runs only when Add sample data is checked — see 15.4 |
| ready | Ready to use | Marks setup complete and loads the application |
Provisioning runs in the background — the SharePoint page stays responsive. Sample data seeding can take a few minutes on slower tenants.
15.4 Sample Data Option
The Add sample data checkbox loads demo data so you can explore the app immediately. Leave unchecked to start with empty transactional lists.
| Setting | Location | Default | Effect |
|---|---|---|---|
| Add sample data (wizard) | Setup wizard checkbox | Unchecked | Seeds transactional demo data when checked at setup time |
| Enable sample data on setup | Settings → General | Off (false) | Pre-checks Add sample data on future setup runs |
Always seeded (even without sample data checkbox)
These master-data rows are created whenever lists are provisioned:
| List | Seed content |
|---|---|
| Departments | Professional Services, Engineering |
| Teams | Delivery (Prof. Services), Platform (Engineering) |
| TaxProfiles | Standard (0%, default) |
| Clients | Acme Corporation (billing@acme.example), Contoso Ltd |
| Projects | Website Redesign, Internal Training, Time Off (PTO) |
| Tasks | Discovery workshops, UI design, Course development |
| Holidays | NY Day, Memorial Day, July 4, Labor Day, Thanksgiving, Christmas (2026) |
| ExpenseCategories | Travel, Meals, Supplies, Software, Other |
| EmailTemplates | 6 default notification templates (invoice, reminder, approval, rejection, submission, PTO) |
| InvoiceTemplates | 8 PDF layout templates (Standard, Consulting, T&M, Minimal, Executive, Modern, Project Summary, Retainer) |
| RolePermissions | Full member/manager/admin matrix (teamLead cloned from manager) |
| AppSettings | Empty JSON blobs; DashboardName=Time & Billing Hub; ProvisioningVersion=1.0.0 |
Transactional sample data (only when Add sample data is checked)
Additional demo data is created for the current signed-in user (@currentUser):
| List | Content |
|---|---|
| Periods | 4 weekly periods (3 weeks back + current week) |
| Timesheets | 3 approved + 1 draft for current user |
| TimeEntries | Hours on Website Redesign tasks across weeks |
| Invoices | INV-SAMPLE-001 (sent, Acme), INV-SAMPLE-002 (draft, Contoso) |
| InvoiceLines | Line items tied to sample invoices |
Sample transactional data can be cleared programmatically via ListProvisioningService.clearSeedData() — there is no in-app Clear sample data button yet. Approved sample timesheets cannot be deleted in the UI; draft timesheets can.
15.5 Required Lists (18 — gate completion)
Setup is complete when all of these lists exist with the correct schema:
- UserRoles, Employees, Departments, Teams, RolePermissions
- Clients, Projects, Tasks, TaxProfiles
- Periods, Timesheets, TimeEntries, TimesheetApprovals
- Holidays, PTORequests, ExpenseCategories, Expenses
- AppSettings
15.6 Extended Lists (provisioned during setup, not required for gate)
- Rates, Invoices, InvoiceLines, Retainers, Payments
- EmailTemplates, InvoiceTemplates
- CustomFields, CustomFieldValues, UserSettings, AuditLogs
- TimesheetDocuments (document library with Receipts, Invoices, Attachments folders)
Lists are hidden from Site Contents after provisioning but remain URL-accessible for administrators.
15.7 Post-Setup Administrator Checklist
- Settings → General — company name, company address, support email
- Settings → Email integration — confirm Chronodat Mail API or configure Microsoft Graph Mail.Send
- Settings → Email templates — review Default Invoice Email
- Team Members — add employees and link SharePoint users
- Departments / Teams — set managers and team leads for approval routing
- Clients — add billing email and billing address for each client you will invoice
- Projects — set approvers, budgets, and billable flags
- Settings → Roles & Permissions — assign admin and manager roles
- Settings → Workflows — confirm approval required and approver source
- SharePoint list permissions — configure groups per README (UX role gating is not a security boundary)
15.8 Subscription and Trial
Time & Billing Hub includes a 14-day free trial per site collection. If a subscription expires, the app may show a lock screen until an administrator renews. Chronodat Mail API (default email mode) requires an active subscription for the tenant.