📅 AdvancedTC - Advanced Timesheet Calendar

A custom app for ERPNext that provides an advanced calendar view for managing timesheet details (Time Sheet Detail) with complete CRUD functionality, export and reporting capabilities.

🎯 Why AdvancedTC?

Limitations of the Base ERPNext System

ERPNext, while being an excellent open-source ERP system, has some significant limitations in timesheet management that motivated the development of this custom app:

🚫 Standard System Issues

1. Limited Calendar View: ERPNext provides a calendar view only for main Timesheets, but not for Timesheet Details, which can only be managed through tabular interface, making it difficult to visualize and edit individual activities temporally

2. Unintuitive Interface: Timesheet Detail management occurs through traditional forms, without drag & drop or visual editing

3. Limited Filters: The base system doesn't offer advanced filters for Employee, Project, Activity Type and Task in a single view

4. Limited Export: Lack of custom CSV export functionality with detailed statistics

5. Complex Break Management: Difficulty in managing breaks and lunch breaks within activities

6. Missing Task-Employee-Project Validation: ERPNext allows creating tasks for a project and assigning them to employees who are not associated with that project, causing confusion in management and access control issues

7. No Weekly Timesheet Management: The standard system does not automatically group activities into weekly timesheets, making reporting and data consistency more difficult

✅ Solutions Implemented in AdvancedTC

• Modern Calendar View: Interface based on FullCalendar.js with intuitive temporal visualization
• Drag & Drop: Visual activity modification with dragging and resizing
• Advanced Filters: Integrated filter system in the sidebar for efficient navigation
• Smart Export: CSV export functionality
• Advanced Break Management: Native support for breaks with automatic creation of separate activities
• Task-Employee-Project Validation: Control system that prevents assignment of tasks to employees not associated with the project
• Weekly Timesheet Management: Automatic grouping of activities into weekly timesheets via dedicated backend and frontend logic
• Complete Integration: Maintains full compatibility with the existing ERPNext system

📑 Table of Contents

1. Why AdvancedTC?
2. Key Features
3. Prerequisites
4. Installation
5. Accessing the Application
6. Configuration Verification
7. Project Access Control
8. Troubleshooting
9. Usage
10. Technical Architecture
11. Detailed Features
12. Customization
13. Configuration
14. Troubleshooting
15. Additional Features
16. Additional Resources
17. Contributing
18. License
19. Support
20. Changelog
21. Project Information

🎯 Key Features

• Interactive Calendar View: Modern visualization with FullCalendar.js
• Advanced Filters: Employee, Project, Activity Type and Task with role-based visibility
• Complete CRUD Management: Create, edit, delete activities
• Drag & Drop: Move and resize activities
• ERPNext Integration: Complete with Timesheet and Timesheet Detail
• Project Assignment System: Uses ERPNext's "Assign To" functionality for project access control
• Role-Based Access: Managers see all projects, employees only see assigned projects
• Export and Reporting: CSV export with detailed statistics
• Break Management: Complete support for breaks and lunch breaks
• Customization: Dynamic colors and advanced configurations
• Automatic Workspace Creation: Dedicated workspace created during installation
• Apps Screen Integration: Direct access from ERPNext apps section

📋 Prerequisites

• ERPNext: v15+ or Frappe Framework v15+
• Python: 3.10+ (as specified in pyproject.toml)
• Modules: Access to ERPNext Timesheet modules
• Permissions: Timesheet and Timesheet Detail management
• Browser: Modern with ES6+ support
• Bench: Properly configured for ERPNext site

🚀 Installation

1. Get the app

# Navigate to the main bench directory
cd /path/to/frappe-bench

# Download the app from repository
bench get-app https://github.com/CupoMeridio/advanced_tc.git

2. Verify app structure

# Verify the structure is correct
ls /path/to/frappe-bench/apps/advanced_tc/
# You should see: advanced_tc/, setup.py, pyproject.toml, README.md, license.txt

# Verify essential files
ls /path/to/frappe-bench/apps/advanced_tc/advanced_tc/
# You should see: __init__.py, hooks.py, modules.txt, install.py, api/, public/, config/

3. Install the app

# Start the bench
bench start

Open a new terminal, navigate to the bench folder and run:

# Install the app on specific site
bench --site [site-name] install-app advanced_tc

4. Migrate the database

# Run migration to apply database changes
bench --site [site-name] migrate

5. Restart the server

bench restart

🚀 Accessing the Application

After successful installation, you can access Advanced Timesheet Calendar in three ways:

1. Apps Section

• Navigate to your ERPNext desktop
• Click on the "Apps" section
• Look for the "Advanced Timesheet Calendar" icon with a calendar symbol
• Click the icon to launch the application

2. Dedicated Workspace

• Navigate to the "Advanced Timesheet Calendar" workspace
• This workspace is automatically created during installation
• Contains shortcuts and links to the application

3. Direct Link

• Navigate directly to: https://your-site.com/app/advanced_tc
• Or use the relative path: /app/advanced_tc

First Time Setup

For Managers:

• You will immediately see all open projects in the calendar
• Use ERPNext's "Assign To" feature to assign projects to employees

For Employees:

• If no projects are assigned, you'll see a message to contact HR
• Once projects are assigned, you'll see only your assigned projects

✅ Configuration Verification

Required File Structure

The app must have this structure to work correctly:

advanced_tc/
├── advanced_tc/
│   ├── __init__.py                    # App version (0.0.1)
│   ├── hooks.py                       # App configuration
│   ├── modules.txt                    # Modules (advanced_tc)
│   ├── patches.txt                    # Database patches
│   ├── install.py                     # Installation script
│   ├── pyproject.toml                 # Python project config
│   ├── api/
│   │   ├── __init__.py
│   │   └── timesheet_details.py       # Backend API
│   ├── public/
│   │   ├── .gitkeep
│   │   ├── css/
│   │   │   └── timesheet_calendar.css # CSS styles
│   │   ├── images/                    # Image assets
│   │   └── js/
│   │       └── timesheet_calendar.js  # JS utilities
│   ├── config/                        # Configuration files (empty)
│   ├── templates/
│   │   ├── __init__.py
│   │   └── pages/                     # Template pages
│   └── advanced_tc/
│       ├── .frappe                    # Frappe metadata
│       ├── __init__.py
│       └── page/
│           └── advanced_tc/
│               ├── __init__.py
│               ├── advanced_tc.json   # Page configuration
│               └── advanced_tc.js     # Frontend logic
├── .gitignore                         # Git ignore rules
├── .pre-commit-config.yaml            # Pre-commit hooks
├── setup.py                           # Python setup
├── pyproject.toml                     # Project configuration
├── README.md                          # Documentation (English)
├── README.it.md                       # Documentation (Italian)
├── license.txt                        # License

Key Components

1. hooks.py: Configures app_name="advanced_tc", CSS, JS and workspace with automatic app screen integration
2. install.py: Installation script with workspace creation and informative messages
3. advanced_tc.json: Defines the main page configuration
4. advanced_tc.js: Frontend logic for interactive calendar
5. timesheet_details.py: Backend API endpoints for timesheet management
6. timesheet_calendar.css/js: Styling and utility functions for the calendar
7. logo.svg/logo.png: Application logos for the apps screen

🔐 Project Access Control

Role-Based Project Visibility

AdvancedTC implements a sophisticated project access control system using ERPNext's native "Assign To" functionality:

For Managers (System Manager, HR Manager, HR User)

• Full Access: Can view and create activities for all open projects
• No Restrictions: Complete project visibility in filters and dialogs
• Assignment Control: Can assign projects to employees using ERPNext's "Assign To" feature

For Employees

• Restricted Access: Can only view projects assigned to them via "Assign To"
• Automatic Filtering: Project filters and activity creation dialogs show only assigned projects
• No Assignment Access: If no projects are assigned, they see an empty list with instructions to contact HR

How to Assign Projects to Employees

1. Navigate to Project: Go to any Project document in ERPNext
2. Use Assign To: Click the "Assign To" button in the sidebar
3. Select Employee: Choose the employee(s) to assign to the project
4. Automatic Access: The employee will immediately see the project in AdvancedTC

Security Features

• No Fallback Access: Employees without assignments cannot see any projects
• Clear Messaging: Users are informed when they need HR assistance for project assignment
• Consistent Filtering: Same access rules apply to sidebar filters and activity creation dialogs
• ERPNext Integration: Uses native ERPNext ToDo system for assignments

🔧 Troubleshooting

Error "No module named 'advanced_tc'"

Cause: The app was not copied correctly to the apps/ directory

Solution:

# Verify the app is in the correct directory
ls /path/to/frappe-bench/apps/advanced_tc

# If not there, copy the app
cp -r /path/to/advanced_tc /path/to/frappe-bench/apps/

# Verify essential files exist
ls /path/to/frappe-bench/apps/advanced_tc/advanced_tc/hooks.py
ls /path/to/frappe-bench/apps/advanced_tc/advanced_tc/__init__.py

# Just restart bench
# Sometime restarting bench resolve the issue
bench restart

# or stop and restart manually with Ctrl+C and then
bench start

Error "InvalidGitRepositoryError"

Cause: The folder is not a valid Git repository

Solution:

# Option 1: Initialize as Git repository
cd /path/to/advanced_tc
git init
git add .
git commit -m "Initial commit"

# Option 2: Manual copy (simpler)
cp -r /path/to/advanced_tc /path/to/frappe-bench/apps/
cd /path/to/frappe-bench
bench --site [site-name] install-app advanced_tc

Installation error

Verify:

1. Python Version: Make sure to use Python 3.10+
2. Permissions: Verify ERPNext base permissions on Timesheet doctypes
3. Dependencies: Check that ERPNext v15+ is installed
4. Logs: Check logs for specific errors

# Check logs
tail -f /path/to/frappe-bench/logs/web.log
tail -f /path/to/frappe-bench/logs/worker.log

App is installed but not working

Verify:

1. Migration: Make sure migration is completed
2. User permissions: Verify user has necessary ERPNext base roles
3. Cache: Clear browser cache
4. Restart: Completely restart the bench

# Force migration
bench --site [site-name] migrate

# Clear cache
bench --site [site-name] clear-cache

# Restart everything
bench restart

📖 Usage

Accessing the Calendar View

1. Login to ERPNext
2. Go to AdvancedTC module or search "Advanced Timesheet Calendar"
3. View the calendar view with all activities

Main Features

🔍 Advanced Filters

• Employee: Filter by specific employee (managers see all, employees see only themselves)
• Project: Filter by project (based on "Assign To" assignments)
• Activity Type: Filter by activity type
• Task: Filter by specific task

➕ Adding Activities

1. Click "Add Activity" or select a time range in the calendar
2. Fill the form with:
   • Employee (required)
   • From Time / To Time (required)
   • Project (optional)
   • Task (optional)
   • Activity Type (optional)
   • Description (optional)
   • Break Start/End (optional)
3. Click "Create" to save

✏️ Editing Activities

• Drag & Drop: Drag the activity to change date/time
• Resize: Drag the borders to modify duration
• Edit Dialog: Click on the activity to open the edit dialog

🗑️ Deleting Activities

1. Click on the activity to open the dialog
2. Click "Delete"
3. Confirm deletion

📊 Export and Reporting

Accessing the Feature: The export functionality is accessible through the "Generate Report" button in the sidebar.

How to use:

1. Navigate in the calendar to select the desired period
2. Apply any filters (employee, project) if needed
3. Click the "Generate Report" button in the sidebar
4. View the summary dialog with:
   • Total hours for the displayed period
   • Detailed breakdown by employee
   • Breakdown by project
   • Breakdown by activity type
5. Click "Export CSV" to download data in CSV format

⚙️ Settings

1. Click "Settings" in the sidebar
2. Configure preferences:
   • Default work shift time
   • Default break time
3. Save settings

📅 Calendar Views

• Month: Complete monthly view
• Week: Weekly view (default)
• Day: Detailed daily view

🏗️ Technical Architecture

Backend (Python)

API Endpoints

File: api/timesheet_details.py

@frappe.whitelist()
def get_timesheet_details(start_date=None, end_date=None, filters=None):
    """Retrieve timesheet activities for the calendar"""
    
@frappe.whitelist()
def create_timesheet_detail(data):
    """Create a new timesheet activity"""
    
@frappe.whitelist()
def update_timesheet_detail(name, data):
    """Update existing activity"""
    
@frappe.whitelist()
def delete_timesheet_detail(name):
    """Delete timesheet activity"""

Business Logic

1. Weekly Timesheet Management:

   • Automatic creation if non-existent
   • Automatic calculation of week start (Monday)
   • Automatic deletion of empty timesheets

2. Data Validation:

   • Time overlap control
   • Time range validation
   • User permission verification

3. Hours Calculation:

   • Automatic duration calculation
   • Break and pause management
   • Configurable rounding

Frontend (JavaScript)

Main Components

File: public/js/advanced_tc.js

class AdvancedTimesheetCalendar {
    constructor() {
        this.init_calendar();
        this.setup_filters();
        this.setup_event_handlers();
    }
    
    init_calendar() {
        // FullCalendar initialization
    }
    
    setup_filters() {
        // Filter configuration
    }
    
    handle_time_selection(info) {
        // Time selection handling
    }
}

File: public/js/timesheet_calendar.js

window.TimesheetCalendarUtils = {
    showSummaryDialog: function(events, startDate, endDate) {
        // Summary dialog and export
    },
    
    exportToCSV: function(activities, filename) {
        // CSV export functionality
    }
};

Used Libraries

• FullCalendar.js: Main calendar component
• Frappe Framework: ERPNext integration
• jQuery: DOM manipulation and AJAX

ERPNext Integration

Involved DocTypes

• Timesheet: Weekly activity container
• Timesheet Detail: Single activity/timesheet entry
• Employee: Employee information
• Project: Project connection
• Task: Task connection
• Activity Type: Activity categorization

🚀 Detailed Features

1. Weekly Timesheet Management

The app implements intelligent timesheet management:

• Automatic Creation: Creates weekly timesheets automatically when needed
• Work Week Management: Automatically calculates week start (Monday)
• Smart Deletion: Removes empty timesheets automatically

2. Dynamic Color System

Each project automatically receives a consistent color:

• Consistent Colors: Same project = same color always
• Uniform Distribution: Algorithm distributes colors evenly
• No Configuration: Works automatically without setup

3. Validation and Controls

The app includes automatic controls to ensure data quality:

• Overlap Control: Prevents time overlaps between activities
• Time Validation: Verifies that times are logical and valid
• Permission Control: Verifies user can modify the data
• Duration Validation: Checks that activities have reasonable duration

4. Advanced Drag & Drop

Intuitive drag functionality:

• Move Activities: Drag to change date and time
• Resize: Modify duration by dragging borders
• Visual Feedback: Notifications and loading states
• Automatic Rollback: Cancels changes on error

5. Filter System

Advanced filters for efficient navigation:

• Employee: Filter by employee (with permission control)
• Project: Filter by project (based on assignments)
• Activity Type: Filter by activity type
• Task: Filter by specific task
• Combinations: Use multiple filters simultaneously

6. Advanced Export and Reporting

Complete export and analysis functionality:

• CSV Export: Export data in CSV format with all details
• Summary Dialog: Display statistics for selected period
• Detailed Breakdown: Analysis by employee, project and activity type
• Export Filters: Export only filtered data

7. Break and Pause Management

Complete support for break management:

• Break Start/End: Define break times within activity
• Automatic Calculation: Break hours are subtracted from total
• Validation: Automatic checks for valid break times
• Actual Hours: Precise calculation of worked hours

🎨 Customization

The app offers various customization options:

Visual Customization

• Automatic Colors: Dynamic color assignment for projects
• Responsive Interface: Adapts to different screen sizes
• Theme Support: Compatible with ERPNext themes
• Custom Styling: Modify CSS for personalized appearance

Extensibility

• Modular Architecture: Easy to extend with new features
• API Integration: Add custom endpoints as needed
• Event Hooks: Integrate with ERPNext workflows
• Custom Fields: Support for additional data fields

🔧 Configuration

Permissions

The app uses ERPNext standard roles and permissions:

Required ERPNext Roles:

• Employee: Basic timesheet access for own records
• HR User: Extended HR functionality
• HR Manager: Full HR management capabilities
• System Manager: Complete system access

Required DocType Access:

• Timesheet, Timesheet Detail, Employee, Project, Task, Activity Type

Performance Optimization

For optimal performance with large datasets:

• Period Filters: Use date range filters to limit data
• Database Optimization: Automatic indexing for faster queries
• Caching: Intelligent caching of frequently accessed data
• Pagination: Efficient data loading for large result sets

Default Configurations

The app includes sensible defaults:

• CSS and JavaScript: Automatically loaded assets
• Activity Types: Pre-configured common activity types
• Calendar Settings: Optimized for business use
• Performance: Efficient caching and indexing

🐛 Troubleshooting

Common Issues

1. Calendar doesn't load

Solutions:

• Rebuild and restart: bench build && bench restart
• Verify user has appropriate ERPNext roles
• Clear browser cache (Ctrl+Shift+R)
• Check browser console for JavaScript errors

2. API Errors

Solutions:

• Check ERPNext error logs
• Verify user permissions for Timesheet DocType
• Ensure proper site configuration

3. Styles not applied

Solutions:

• Recompile assets: bench build --app advanced_tc
• Hard refresh browser (Ctrl+F5)
• Check CSS file paths

4. Drag & Drop Issues

Common causes:

• Insufficient permissions
• Time overlaps with existing activities
• Validation errors

Solutions:

• Check user permissions
• Verify no time conflicts
• Review activity validation rules

For advanced debugging and development, the app includes:

• Backend Logging: Detailed error tracking and debugging
• Frontend Logging: Browser console debugging tools
• Testing Framework: Unit and integration tests
• Development Tools: Code quality and testing utilities

🚀 Additional Features

Advanced Break Management

• Automatic Break Rules: Configurable break policies
• Net Hours Calculation: Precise work time calculation
• Break Validation: Ensures breaks are within activity time

Keyboard Shortcuts

• Ctrl+N: Create new activity
• Ctrl+R: Refresh calendar
• Esc: Close dialogs

📚 Additional Resources

• 📖 Technical Documentation - Detailed technical architecture, API reference, and development guide
• ERPNext Documentation
• Frappe Framework Documentation
• FullCalendar.js Documentation

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the project
2. Create a feature branch
3. Commit your changes with clear messages
4. Test your changes thoroughly
5. Submit a Pull Request

Development Guidelines

• Follow ERPNext coding standards
• Include appropriate documentation
• Test all functionality before submitting
• Ensure compatibility with latest ERPNext version

📝 License

This project is released under GPL-3.0 license. See the license.txt file for complete details.

Commercial Use

• ✅ Allowed: Commercial use
• ✅ Allowed: Modification and distribution
• ✅ Allowed: Private use
• ❗ Required: Maintain GPL-3.0 license
• ❗ Required: Make source code available

Debug Information

When reporting an issue, include:

# ERPNext version
bench version

# Error logs
bench logs

# Browser configuration
# - Browser version
# - Console errors (F12)
# - Network tab for API errors

FAQ

Q: How to add new Activity Types? A: Go to ERPNext > Setup > Activity Type and create new types.

Q: Can I customize colors? A: Yes, modify the get_event_color() function in api/timesheet_details.py.

Q: How to export data for long periods? A: Use filters to limit the dataset, then export to CSV.

🎓 Project Information

This project was developed as an internship activity at Youbiquo company by two Computer Engineering students from the University of Salerno:

• Fabrizio D'Errico
• Vittorio Postiglione

---

Developed with ❤️ for the ERPNext community