TimeTracker/docs/features/TIME_ENTRY_TEMPLATES.md

Time Entry Templates Feature

Overview

Time Entry Templates is a productivity feature that allows users to create reusable templates for frequently logged activities. This feature saves time and ensures consistency when tracking recurring tasks.

Implementation Status

✅ Complete - Fully implemented and tested

Features

Core Functionality

• ✅ Create, read, update, and delete templates
• ✅ Template includes project, task, duration, notes, tags, and billable settings
• ✅ Usage tracking (count and last used timestamp)
• ✅ One-click start timer from template
• ✅ Template selector in dashboard timer modal
• ✅ Pre-fill manual time entries from templates
• ✅ API endpoints for programmatic access

User Interface

• ✅ Template management page with grid layout
• ✅ Create and edit forms with project/task selectors
• ✅ Template cards showing usage statistics
• ✅ Dashboard integration for quick access
• ✅ Most recently used templates prioritized

Backend

• ✅ TimeEntryTemplate model with full relationships
• ✅ CRUD routes with validation
• ✅ Usage tracking and analytics events
• ✅ Integration with existing timer and time entry systems
• ✅ User-scoped templates (privacy)

Technical Details

Database Schema

class TimeEntryTemplate(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(db.Integer, db.ForeignKey('users.id'))
    name = db.Column(db.String(200), nullable=False)
    description = db.Column(db.Text)
    project_id = db.Column(db.Integer, db.ForeignKey('projects.id'))
    task_id = db.Column(db.Integer, db.ForeignKey('tasks.id'))
    default_duration_minutes = db.Column(db.Integer)
    default_notes = db.Column(db.Text)
    tags = db.Column(db.String(500))
    billable = db.Column(db.Boolean, default=True)
    usage_count = db.Column(db.Integer, default=0)
    last_used_at = db.Column(db.DateTime)
    created_at = db.Column(db.DateTime)
    updated_at = db.Column(db.DateTime)

Routes

• GET /templates - List all templates
• GET /templates/create - Create template form
• POST /templates/create - Create new template
• GET /templates/<id> - View template details
• GET /templates/<id>/edit - Edit template form
• POST /templates/<id>/edit - Update template
• POST /templates/<id>/delete - Delete template

API Endpoints

• GET /api/templates - Get all templates (JSON)
• GET /api/templates/<id> - Get single template (JSON)
• POST /api/templates/<id>/use - Mark template as used

Timer Integration

• GET /timer/start/from-template/<id> - Start timer directly from template
• GET /timer/manual?template=<id> - Pre-fill manual entry form
• Template selector in dashboard start timer modal

Testing

Comprehensive test suite includes:

• ✅ Model tests (creation, properties, relationships)
• ✅ Route tests (CRUD operations, validation)
• ✅ API tests (endpoints, responses)
• ✅ Integration tests (timer start, usage tracking)
• ✅ Smoke tests (page rendering, workflows)

Test file: tests/test_time_entry_templates.py (599 lines)

Usage Examples

Creating a Template

template = TimeEntryTemplate(
    user_id=current_user.id,
    name="Daily Standup",
    project_id=project.id,
    task_id=task.id,
    default_duration_minutes=15,
    default_notes="Discussed progress and blockers",
    tags="meeting,standup",
    billable=False
)
db.session.add(template)
db.session.commit()

Starting Timer from Template

# In routes/timer.py
@timer_bp.route('/timer/start/from-template/<int:template_id>')
@login_required
def start_timer_from_template(template_id):
    template = TimeEntryTemplate.query.get_or_404(template_id)
    # Create timer with template data
    new_timer = TimeEntry(
        user_id=current_user.id,
        project_id=template.project_id,
        task_id=template.task_id,
        notes=template.default_notes,
        tags=template.tags,
        billable=template.billable
    )
    template.record_usage()
    db.session.commit()

API Usage

// Fetch templates
fetch('/api/templates')
  .then(res => res.json())
  .then(data => {
    data.templates.forEach(template => {
      console.log(template.name, template.usage_count);
    });
  });

// Use template
fetch(`/api/templates/${templateId}/use`, {
  method: 'POST',
  headers: { 'X-CSRFToken': csrfToken }
});

Migration

No database migration required for existing installations - the feature is additive:

# Run migrations to create time_entry_templates table
flask db upgrade

Or for Alembic-based migrations:

alembic upgrade head

User Documentation

See Time Entry Templates User Guide for:

• Step-by-step usage instructions
• Best practices and tips
• Troubleshooting guide
• API reference

Related Features

• Time Tracking: Core time entry and timer functionality
• Projects: Template organization by project
• Tasks: Template organization by task
• Reports: Template usage analytics (future enhancement)

Future Enhancements

Potential improvements:

• Template sharing between team members
• Template categories/folders
• Template suggestions based on usage patterns
• Bulk operations on templates
• Template import/export
• Template analytics dashboard

Maintenance

Database Cleanup

Templates can be cleaned up periodically:

# Delete templates not used in 6+ months
from datetime import datetime, timedelta
cutoff = datetime.utcnow() - timedelta(days=180)
TimeEntryTemplate.query.filter(
    TimeEntryTemplate.last_used_at < cutoff
).delete()

Monitoring

Key metrics to track:

• Template creation rate
• Template usage rate
• Most popular templates
• Templates never used
• Average templates per user

Support

For issues or questions:

• Check the User Guide
• Review Project Structure
• See Testing Guide
• Open an issue on GitHub

Changelog

v1.0.0 (Initial Release)

• Complete CRUD operations for templates
• Dashboard integration
• Timer integration
• API endpoints
• Comprehensive test suite
• User documentation