Official Technical Documentation & User Manual
User Manual › Volume 6: Field Service Job Cards, Technician Dispatch, Projects, Tasks & Time Billing
Verified Guide • Updated 16 Oct 2026
User Manual Volume 6: Field Service Job Cards, Technician Dispatch, Projects, Tasks & Time Billing Verified Guide

#19: Enterprise Projects Portfolio, Milestones, Resource Capacity, PSA Financials & Governance Studio

Updated 21 hours ago 9 min read 1 views
Volume 6 • Field Service, Projects & PSA Engine

Enterprise Projects Portfolio, Milestones, Resource Capacity, PSA Financials & Governance Studio

Master multi-phase client delivery, Professional Services Automation (PSA), milestone billing, cross-functional team allocation, project expense tracking, and 1-click project-to-invoice revenue sweeps.

In This Article

1. PSA Accounting 101: The 5 Commercial Project Billing Models

While a **Job Card** is designed for a single-visit field callout or repair, an **Enterprise Project** (`PRJ-XXXX`) manages multi-day, multi-week, or multi-month engagements containing dozens of deliverables (Tasks), staged commercial sign-offs (Milestones), assigned specialist roles, and direct vendor expenses.

In Keystone X, every Project is governed by one of **5 Commercial Billing Models** (configurable in `/project/settings`):

Billing Model Best Used For How Keystone X Tracks WIP & Bills the Client
1. Hourly (Time & Materials) Consulting, software engineering, legal/accounting advisory, ad-hoc engineering Every billable hour logged on any Task inside the project multiplies by the task/project `hourly_rate` and accumulates as **Unbilled WIP**. Clicking **Invoice Project** sweeps every unbilled time entry into an itemized Tax Invoice.
2. Milestone Billing Turnkey installations, construction/solar rollouts, phased implementation projects You divide the contract into commercial **Milestones** (e.g., *Phase 1: 40% Deposit & Design*, *Phase 2: 40% Equipment Delivery*, *Phase 3: 20% Handover*), each with a fixed `amount`. When a milestone is marked `Completed`, its value enters **Unbilled WIP** and is swept onto the next Tax Invoice.
3. Fixed Fee Flat-rate Turnkey Contracts with a single agreed `budget_amount` Your team still logs hours and expenses against tasks so you can monitor internal **Capacity Burn** and profitability, but clicking **Invoice Project** bills the agreed contract `budget_amount` (if no individual billable time/milestones are queued).
4. Retainer Monthly managed services or ongoing SLA support envelopes Tracks monthly hours burned against `estimated_hours` capacity and works seamlessly alongside Recurring Invoices (`/RecurringInvoice`).
5. Internal (Non-Billable) R&D, internal IT upgrades, marketing campaigns, or CapEx initiatives Tracks task progress, milestones, hours, and internal costs without generating client-facing Accounts Receivable invoices.

2. The Projects Portfolio Command Center (/project)

Navigate to **Operations → Projects** (`/project`) to view your organization's entire project portfolio.

📸 SCREENSHOT PLACEHOLDER projects-portfolio-command-center.png

How to capture this screenshot:

  1. Navigate to /project in List View (`?view=list`).
  2. Ensure at least 2–3 sample projects exist with logged task hours, milestones, and budgets.
  3. Capture the top header buttons (List View, Kanban Board, All Tasks, Customize, New Project), the 4 Portfolio Telemetry KPI Cards, the Stage Filter Pills, and the Projects DataTable.
The 4 Portfolio Telemetry KPI Cards
  • 1. Active Delivery: Counts projects currently in active execution (e.g., `Planning` or `In Progress`), highlighting how many are `In Progress` vs. `On Hold`.
  • 2. Portfolio Budget & WIP: Displays the combined contract budget (`budget_amount`) across all projects, plus two live financial badges: **Unbilled WIP (`R`)** ready to be invoiced and **Billed Revenue (`R`)** already converted to Tax Invoices.
  • 3. Total Hours Logged vs. Est. Capacity: Sums all hours logged across all project tasks (`logged_hours`) against the portfolio's total estimated hour capacity (`estimated_hours`), with a real-time **Capacity Burn %** badge.
  • 4. Task Execution Rate: Shows the overall percentage of completed project tasks across the business (`completed_tasks / total_tasks`) alongside the count of fully `Completed` projects.
Portfolio List Table Columns & Row Actions
Column Header What It Displays
Project & Code Displays a color-coded vertical accent bar matching the project's theme color, the clickable **Project Name**, the unique **Project Code** (`PRJ-0001`), the **Priority** badge (`Critical`, `High`, `Medium`, `Low`), and the **Billing Type** badge (`Hourly`, `Milestone`, `Fixed Fee`, etc.).
Customer & Lead Links directly to the 360° Customer Profile (or displays `Internal Project`), and shows the assigned **Project Manager's** avatar and name.
Stage & Timeline Shows the current workflow stage badge (`Planning`, `In Progress`, `On Hold`, `Completed`) and the target `deadline` date (flashing red with an exclamation icon if overdue).
Delivery Progress A live visual progress bar calculating completion (`progress %`), plus sub-counters for **Tasks Completed (`X/Y`)** and **Milestones Completed (`X/Y`)**.
Time & Financials Shows `Logged Hours / Estimated Hours`, the total **Contract Budget (`R`)**, and live badges for **Unbilled WIP (`R`)** (clickable or ready to invoice) and **Billed (`R`)**.
Row Actions Open Project Workspace () (`/project/details/{id}`), 1-Click Invoice Unbilled WIP () (`/project/convertToInvoice/{id}`), Edit Project Settings () (`/project/edit/{id}`), and Delete Project ().

3. Drag-and-Drop Portfolio Kanban Board (/project/kanban)

Clicking **Kanban Board** (`/project?view=board` or `/project/kanban`) renders your entire project portfolio as draggable cards organized into workflow stage columns.

  • Live Stage Budget Totals: The header of each stage column automatically calculates and displays the total contract value (`R`) of all projects currently sitting in that stage.
  • Priority Filter Bar: Instantly filter the board by `All Priorities`, `Critical`, `High`, `Medium`, or `Low`.
  • Drag-and-Drop Stage Updates: Dragging a project card between columns updates its stage immediately via `project/updateStatusAjax` and recalculates column counts.

4. Inside the 6-Tab Project Execution Workspace (/project/details/{id})

Clicking any project opens its dedicated **6-Tab Execution Workspace** (`/project/details/{id}`). At the top of the workspace, you have an **Interactive Stage Stepper Bar** (allowing 1-click stage transitions), action buttons for **+ Milestone**, **+ New Task**, and **Invoice Project**, and 4 dedicated Project KPI Cards (**Delivery Progress %**, **Time & Capacity Burn**, **Budget & Financials**, and **Target Deadline & Team Size**).

📸 SCREENSHOT PLACEHOLDER projects-6tab-execution-workspace.png

How to capture this screenshot:

  1. Navigate to /project/details/{id} for an active project.
  2. Capture the Project Header Banner (showing the Project Code, Customer link, Stage Stepper, and Invoice Project button), the 4 Project KPI cards, and the 6-tab navigation bar with Tab 1 (Tasks & Execution) open.
Workspace Tab Tools, Controls & Financial Workflows
Tab 1: Tasks & Execution (#tab-tasks)
  • Milestone Filter & Dual Sub-View Switcher: Filter tasks by a specific **Milestone Phase** (`#milestoneTaskFilter`) and toggle instantly between a structured **Table View** and an in-project **Drag-and-Drop Task Kanban Board**!
  • Live Stopwatch & Manual Time Logging: Start/stop a live task timer (`task/startTimer` / `task/stopTimer`) or click the clock icon to log hours directly against any task.
  • Expandable Per-Task Time Ledger: Click the hours badge on any task row to expand an inline sub-table showing every individual time log entry, who worked it, and whether it is `Unbilled` or `Billed`.
Tab 2: Milestones & Roadmap (#tab-milestones)
  • Seed Standard Blueprints Button (project/applyMilestoneTemplates): Populates the project with your organization's standard phase milestones (configured in `/project/settings`), automatically calculating each milestone's due date offset from the project's start date!
  • 1-Click Milestone Completion Toggle (project/toggleMilestone): Click the check circle next to any milestone to mark it `Completed` (`In Progress` ↔ `Completed`). Completing a billable milestone immediately queues its fixed `amount` into **Unbilled WIP** ready for invoicing.
Tab 3: Timesheets (#tab-timesheets) Displays a consolidated chronological ledger of every time entry logged across all tasks in the project, showing the **Date**, **Team Member**, **Task Name**, **Work Notes**, **Hours**, **Billable Rate (`R/hr`)**, **Calculated Billable Value**, and **Billing Status** (`Unbilled WIP` vs. `Invoiced`).
Tab 4: Financials & Billing (#tab-financials)
  • Unbilled WIP Summary Banner: Shows exact unbilled task hours (`R`) and completed unbilled milestones (`R`) with a 1-click **Convert Unbilled WIP to Invoice** button.
  • Project Invoices Table: Lists every Tax Invoice (`INV-XXXX`) generated from or linked to this project (`project_id`), showing invoice totals, paid amounts, and outstanding balances.
  • Project Direct Expenses Table & Modal (#expenseModal): Log direct project costs (`project/addExpense`)—such as travel, equipment hire, or subcontractor disbursements—mapped to an Expense Category and Vendor, and toggle whether the expense is `Billable to Client`.
Tab 5: Team & Stakeholders (#tab-team) Assign staff members to the project (`project/addMember`) with a designated **Project Role** (e.g., *Project Manager*, *Lead Engineer*, *QA Specialist*) selected from your Studio Role Rate Cards. Displays each member's contact details and role badge.
Tab 6: Charter & Notes (#tab-notes) Displays the full **Project Scope & Charter Description** alongside a collaborative **Project Notes & Decisions Feed** (`note/add`) where team members can record meeting minutes, risk logs, and scope variations.

5. How the 1-Click Project Invoicing Engine Works (project/convertToInvoice)

When you click **Invoice Project** (`/project/convertToInvoice/{id}`) from the Project Workspace or Portfolio table, Keystone X executes a smart 3-tier billing sweep:

  1. Tier 1 — Unbilled Task Time Entries: Finds every time entry across all tasks in the project where `is_billable = 1` and `is_billed = 0`. Each entry is added as a descriptive line item on the new Draft Tax Invoice (`Task: [Title] ([Date]) - [Notes]`) using the task's hourly rate (or the project's default `hourly_rate`), and all swept time logs are marked `is_billed = 1`.
  2. Tier 2 — Completed Unbilled Milestones: Finds every project milestone where `status = Completed`, `is_billable = 1`, `is_invoiced = 0`, and `amount > 0`. Each completed milestone is added as a line item (`Milestone: [Title] - [Description]`) and marked `is_invoiced = 1`.
  3. Tier 3 — Fixed Fee Contract Fallback: If the project has no unbilled time logs or milestones queued, and the project uses the `Fixed Fee` billing model with a `budget_amount > 0`, Keystone X automatically creates a single line item for `Project Fixed Fee: [Project Name]` for the contract amount.
  4. Redirects to the Draft Invoice Editor: Once the Draft Invoice is created and linked to `project_id`, Keystone X redirects you straight into `/invoice/edit/{invoiceId}` so you can review line items, attach a payment link, and finalize the Tax Invoice!

6. The 5-Tab Project Customization Studio (/project/settings)

Clicking **Customize** (`/project/settings`) opens the **5-Tab Project Customization Studio**:

Studio Tab What You Can Configure
1. Workflow Stages (#tab-stages) Configure the lifecycle columns for the Portfolio Kanban Board and Project Stage Stepper (e.g., `Planning`, `In Progress`, `On Hold`, `Completed`, `Cancelled`), including custom badge colors, display order, and whether the stage represents a closed/completed state (`is_completed`).
2. Team Roles & Rate Cards (#tab-roles) Define standard delivery roles (e.g., *Principal Architect*, *Senior Technician*, *Project Coordinator*) along with each role's **Default Hourly Billing Rate (`R/hr`)** and badge color.
3. Milestone Blueprints (#tab-milestones) Create standard project phase templates (`title`, `description`, `default_days_offset` from project start date, `default_amount`, and `is_billable`). These blueprints power the **Seed Standard Blueprints** button inside every project workspace.
4. Commercial Billing Models (#tab-billing) Manage the available billing frameworks (`Hourly`, `Fixed Fee`, `Milestone`, `Retainer`, `Internal`), set which model is selected by default on new projects, and customize their descriptions.
5. Defaults & Automation (#tab-defaults)
  • Project Code Prefix (project_code_prefix): Default `PRJ-` (auto-generates `PRJ-0001`, `PRJ-0002`, etc.).
  • Default Billing Rate (project_default_hourly_rate) & Default Stage (project_default_stage): Pre-filled when creating a new project.
  • 3 Governance Switches:
    1. project_auto_seed_milestones: Automatically inject all active Milestone Blueprints whenever a new project is created!
    2. project_require_customer: Enforce selecting a Billing Customer (disallowing unlinked projects unless explicitly marked Internal).
    3. project_auto_complete_on_tasks: Automatically prompt/mark a project as `Completed` when 100% of its tasks are finished.
© 2026 Keystone X — Official Technical Documentation https://keystonex.co.za/docs/volume-6-operations-field-service-helpdesk/19-enterprise-projects-portfolio-milestones-resource-capacity-psa-financials-governance-studio
Was this technical guide helpful?
Back to top