Timesheets

The Timesheets module provides weekly timesheet submission and approval workflows for tracking time spent on PPM projects, WBS elements, and cost categories.

Overview

Accurate time tracking is essential for Earned Value Management, resource utilization reporting, and cost control. ProBeya timesheets extend the core time entry system with PPM-specific context: every entry can be tagged with a project, WBS element, and cost type (CAPEX/OPEX). Timesheets follow a weekly cycle aligned to Monday–Sunday periods with a submit → approve/reject workflow that enforces governance before hours flow into cost calculations.

Getting Started

1. Navigate to PPM > Timesheets to see your current weekly view.
2. Log time entries against a project and WBS element for each day of the week.
3. Review the weekly total hours and verify all entries are complete.
4. Click Submit to send the timesheet for approval.
5. Your manager reviews and approves or rejects the submission.

How It Works

Time Entry Methods

ProBeya supports two methods for logging time:

Live Timer

Start a real-time timer that tracks elapsed time automatically:

1. Click the timer icon on any board or item.
2. The timer starts with startedAt set to the current time and endedAt null.
3. Continue working; the timer widget shows elapsed time.
4. Click Stop to end the timer. Duration is computed server-side: floor((endedAt - startedAt) / 1000) seconds.

Business rule: Only one timer can run per user at a time. Starting a new timer while one is running returns a BAD_REQUEST error. Stop the current timer first.

Manual Entry

Log time after the fact when you forgot to start a timer:

1. Click + Manual Entry on the timesheet grid.
2. Specify the start time, end time, board, and optional item.
3. Add a description and set the billable flag.
4. The system validates that endedAt > startedAt and computes the duration server-side.

Time Entry Fields

Each time entry captures:

Field	Type	Required	Description
Board ID	string	Yes	The board being worked on (validated against org)
Item ID	string	No	Specific task or work item
Description	string	No	Free-text note explaining the work performed
Started At	timestamp	Yes	When the work started
Ended At	timestamp	Timer: auto	When the work ended (null while timer is running)
Duration	integer	Computed	Duration in seconds (computed server-side)
Billable	boolean	No	Whether the time is billable (default: false)

Weekly Timesheet View

The getWeeklyTimesheet endpoint aggregates completed time entries by day for a given week:

• Week boundaries: Aligned to ISO 8601 Monday–Sunday using PostgreSQL DATE_TRUNC('week', ...).
• Daily totals: Total seconds, billable seconds, and entry count per day.
• Week summary: Aggregate total seconds and billable seconds across the week.
• Running timers excluded: Only entries with endedAt IS NOT NULL are included in aggregation to prevent incomplete data from skewing totals.

The response shape:

{
  days: Array<{
    date: string;           // YYYY-MM-DD
    totalSeconds: number;
    billableSeconds: number;
    entryCount: number;
  }>;
  weekTotalSeconds: number;
  weekBillableSeconds: number;
  weekStart: string;        // The Monday of the queried week
}

Active Timer Widget

The getActiveTimer query returns the user's currently running timer (if any), including related item and board data with the full project-workspace navigation chain. This powers the global timer indicator in the UI header, showing which item is being tracked and enabling one-click navigation.

Time Entry Listing

The list endpoint supports rich filtering:

Filter	Type	Default	Description
userId	string	Current user	Filter by the user who tracked time
itemId	string	All items	Filter by specific item
boardId	string	All boards	Filter by specific board
startDate	ISO date	No limit	Entries starting on or after this date
endDate	ISO date	No limit	Entries starting on or before this date
billable	boolean	All	Filter by billable status
limit	number	50	Results per page (max 200)
offset	number	0	Pagination offset

Results are ordered by startedAt descending and include total count and hasMore flag for pagination.

Entry Ownership

Users can only manage their own time entries. The verifyEntryOwnership helper applies a triple filter on every mutation: id + organizationId + userId. This provides defense-in-depth:

• organizationId prevents cross-tenant access
• userId prevents users from modifying other users' entries

Permissions

Action	Required Role
Log, update, or delete own entries	Any member
Start and stop own timers	Any member
View own weekly timesheet	Any member
View another user's timesheet	Manager or Admin
Approve or reject timesheets	Manager or Admin

API Reference

Procedure	Type	Description
timeTracking.startTimer	Mutation	Start a live timer on a board/item
timeTracking.stopTimer	Mutation	Stop a running timer (computes duration)
timeTracking.getActiveTimer	Query	Get the user's currently running timer
timeTracking.logManualEntry	Mutation	Create a time entry with explicit start/end
timeTracking.list	Query	List time entries with filters and pagination
timeTracking.getWeeklyTimesheet	Query	Aggregate time by day for a week
timeTracking.delete	Mutation	Delete a user's own time entry

Tips & Best Practices

تلميح

Log time entries daily rather than at the end of the week. This improves accuracy and makes the weekly submission process faster since entries are already in place.

تلميح

Always tag entries with the correct WBS element and cost type. These fields feed directly into EVM calculations and budget variance reports, so inaccurate tagging can distort project financials.

تلميح

Use the live timer for focused work sessions and manual entry for meetings and ad-hoc activities. The timer ensures accurate duration calculation without relying on memory.

Related Features

• WBS — Work Breakdown Structure elements referenced by time entries
• Budgets & Costs — Time entries feed into actual cost tracking
• EVM — Earned Value calculations rely on timesheet hours
• Resource Reports — Utilization reports aggregate timesheet data