# Timebooking (cf.cplace.ctts.main)

## Overview

The Timebooking app provides a comprehensive Collaborative Time Tracking System (CTTS) for employees to enter, track, and manage work hours across projects and activities. It offers interactive time booking interfaces with calendar and grid views, along with reporting widgets for both employees and project managers.

**Key Capabilities:**
- Interactive time entry with multiple formats (hours:minutes, decimal)
- Daily, weekly, and monthly booking views
- Calendar integration with holiday/non-working day support
- Time validation and approval workflows (month locking/release)
- Representative mode for booking time on behalf of others
- Employee and project manager reporting perspectives

## Dependencies

| App | Qualified Name | Notes |
|-----|----------------|-------|
| cplace Basis | `cf.cplace.platform` | Base platform (always present) |

No additional dependencies are auto-installed with this app.

## Types Provided

**None.** This is a widget-only app that provides time tracking functionality through widgets. Time booking data is managed internally by the app's infrastructure rather than through standard cplace types.

## Widgets Provided

| Widget | Widget Kind | Description | Use Case |
|--------|-------------|-------------|----------|
| **CTTS Timebooking** | `cf.cplace.ctts.main.widget` | Interactive time booking grid for entering work hours | Primary data entry interface for employees to record daily time allocations across multiple projects |
| **Employee Report Grid** | `cf.cplace.ctts.main.employeeReportGrid` | Tabular view of time bookings for an employee | Review aggregated time entries across all booking targets with monthly breakdown |
| **Employee Report Chart** | `cf.cplace.ctts.main.employeeReportChart` | Chart visualization of employee time data | Analyze time distribution patterns and trends visually |
| **Project Leader Report Grid** | `cf.cplace.ctts.main.projectmanagerReportGrid` | Tabular view showing which employees worked on which projects | Project managers monitor resource allocation and verify time entries |
| **Project Leader Report Chart** | `cf.cplace.ctts.main.projectmanagerReportChart` | Chart visualization of project time data | Visual analysis of time distribution across managed projects |

### Widget Details

#### CTTS Timebooking (`cf.cplace.ctts.main.widget`)

The primary time entry interface with features including:
- **Time Formats:** Hours/minutes (8:30) or decimal (8.5/8,5)
- **Time Increments:** Configurable (1 second, 1 minute, 15/30 minutes, 1 hour)
- **Views:** Daily, weekly, or monthly booking modes
- **Validation:** Maximum daily hours, overbooking limits, negative bookings support
- **Workflows:** Month locking/release for approval cycles
- **Favorites:** Quick access to frequently used booking targets
- **Subsequent Booking:** Retroactive time entry within configured limits

#### Report Widgets

Two perspectives with two visualization modes each:

| Perspective | Grid Widget | Chart Widget |
|-------------|-------------|--------------|
| Employee | Shows personal time across all targets | Stacked bar chart of personal time trends |
| Project Manager | Shows team time per project | Stacked bar chart of project time trends |

All report widgets support:
- Date range selection (start/end year and month)
- Representative mode for viewing others' data (with permissions)
- Export functionality (when templates configured)

## Usage Notes

### When to Use This App

- Employee time tracking against projects/activities
- Time-based billing and invoicing requirements
- Resource utilization monitoring
- Approval workflows for time submissions
- Multi-project time allocation analysis

### Configuration Requirements

The app uses app-level configuration for:
- **ALLOWED_GROUPS:** Controls which users can access time tracking features
- **Workspace filtering:** Option to restrict booking targets to current workspace
- **Subsequent booking limits:** Maximum retroactive booking period
- **Validation rules:** Daily limits, overbooking tolerances

### Integration Patterns

- Time booking data entered via the main widget flows to all report widgets
- Report widgets share common data retrieval architecture
- Representative mode uses separate contexts for employee vs. project manager views

### Permissions

Access is controlled through group membership configured at the app level. Users not in allowed groups will see "You cannot make time bookings" or "View not allowed" messages.

### Common Pitfalls

1. **Permission Setup:** Users must be assigned to configured allowed groups
2. **Month Locking:** Released months cannot be edited without revoking release
3. **Workspace Filtering:** Targets in other workspaces may be hidden if filtering is enabled
4. **Time Format Mismatch:** Users may confuse hours:minutes and decimal formats

## Investigation Details

- **Investigation Date:** 2026-02-02
- **Workspace ID:** 534p2pii8j8adcqflckmrb472
- **Pre-installation Apps:** cf.cplace.platform only
- **Post-installation Apps:** cf.cplace.platform, cf.cplace.ctts.main
- **Types Added:** None (widget-only app)
- **Widgets Added:** 5 time tracking widgets