mirror/TimeTracker
1
0
Fork 0
mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-05-19 04:40:32 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
af2232a5b52ddcc73fbf23f49d7bda928242d77a
TimeTracker/docs/features/CALDAV_INTEGRATION.md
T
Dries Peeters 443a797e2d feat: Add CalDAV calendar integration for Zimbra and other CalDAV servers 
Implement comprehensive CalDAV calendar integration to import calendar events
as time entries from CalDAV-compatible servers (Zimbra, Nextcloud, ownCloud).

Features:
- CalDAV client with calendar discovery and event fetching
- Automatic calendar discovery from server URL
- Import calendar events (VEVENT) as time entries
- Project matching from event titles with fallback to default project
- Idempotent sync using IntegrationExternalEventLink to prevent duplicates
- Per-user integration setup (similar to Google Calendar)
- Support for both server URL (with discovery) and direct calendar URL
- SSL certificate verification toggle for self-signed certificates
- Configurable lookback period for event import

Components:
- CalDAVCalendarConnector: Main integration connector with sync logic
- CalDAVClient: Low-level CalDAV client using PROPFIND/REPORT requests
- IntegrationExternalEventLink: Model for tracking imported events (idempotency)
- Setup UI: User-friendly form for configuration
- Comprehensive validation and error handling
- Full test coverage (unit, integration, route tests)
- Documentation: Setup guide and troubleshooting

Technical details:
- Uses icalendar library for parsing VEVENT components
- Handles timezone conversion (CalDAV UTC to app local timezone)
- Skips all-day events (only imports timed events)
- Stores credentials securely (password in access_token, username in extra_data)
- Automatic calendar discovery on first sync if only server URL provided

Migration:
- Adds integration_external_event_links table for sync tracking
- Unique constraint on (integration_id, external_uid) prevents duplicates

Documentation:
- CALDAV_INTEGRATION.md: Complete feature documentation
- CALDAV_QUICK_SETUP.md: Step-by-step setup guide with examples

Closes feature request for CalDAV/Zimbra integration.
2025-12-20 17:28:48 +01:00

5.7 KiB
Raw Blame History

CalDAV Calendar Integration

The CalDAV integration allows you to import calendar events from CalDAV-compatible servers (such as Zimbra, Nextcloud, or ownCloud) as time entries in TimeTracker.

Features

  • Calendar Discovery: Automatically discover available calendars on your CalDAV server
  • Event Import: Import calendar events (VEVENT) as time entries
  • Project Matching: Automatically match events to projects based on event titles
  • Idempotent Sync: Prevents duplicate imports using event UIDs
  • Flexible Configuration: Support for both server URL (with discovery) and direct calendar URL

Supported Servers

  • Zimbra: Fully supported
  • Nextcloud Calendar: Fully supported
  • ownCloud Calendar: Fully supported
  • Other CalDAV servers: Should work with any CalDAV-compatible server

Setup Instructions

1. Navigate to Integrations

  1. Go to Integrations from the main menu
  2. Find CalDAV Calendar in the list
  3. Click Setup CalDAV Calendar

2. Configure Server Connection

Option A: Using Server URL (Recommended)

  1. Server URL: Enter your CalDAV server base URL

    • Example for Zimbra: https://mail.example.com/dav
    • Example for Nextcloud: https://nextcloud.example.com/remote.php/dav

  2. The system will automatically discover your calendars

Option B: Using Direct Calendar URL

  1. Calendar URL: Enter the direct URL to your calendar collection
    • Example: https://mail.example.com/dav/user@example.com/Calendar/
    • This bypasses discovery and connects directly to a specific calendar

3. Authentication

  1. Username: Your CalDAV username (usually your email address)
  2. Password: Your CalDAV password or app-specific password
  3. Verify SSL: Check this box unless using a self-signed certificate

4. Import Settings

  1. Default Project: Select the project where imported events will be assigned
    • If an event title contains a project name, that project will be used instead
  2. Lookback Days: How many days back to import events (default: 90)

5. Save and Test

  1. Click Save Configuration
  2. Go to the integration details page
  3. Click Test Connection to verify connectivity
  4. Click Sync Now to import calendar events

How It Works

Event Import Process

  1. The system fetches calendar events from your CalDAV server within the specified time range
  2. Each event is checked against existing imports (using event UID) to prevent duplicates
  3. Events are converted to time entries with:
    • Start Time: Event start time
    • End Time: Event end time
    • Duration: Calculated automatically
    • Project: Matched from event title or uses default project
    • Notes: Event summary and description
    • Source: Marked as "auto" (automatically imported)

Project Matching

The system attempts to match event titles to project names:

  • If an event title contains a project name, that project is used
  • Otherwise, the default project is used
  • Example: Event "Meeting - Project Alpha" will be assigned to "Project Alpha" if it exists

Idempotency

Each calendar event has a unique UID. The system tracks imported events to prevent duplicates:

  • First import: Event is imported as a new time entry
  • Subsequent syncs: Event is skipped (already imported)

Zimbra-Specific Notes

Finding Your CalDAV URL

For Zimbra, the CalDAV URL typically follows this pattern:

https://mail.yourdomain.com/dav/username@yourdomain.com/Calendar/

Authentication

  • Use your Zimbra email address as the username
  • Use your Zimbra password (or an app-specific password if enabled)

Calendar Discovery

If you provide the server URL (https://mail.yourdomain.com/dav), the system will:

  1. Discover your user principal
  2. Find your calendar home set
  3. List all available calendars
  4. Allow you to select which calendar to sync

Troubleshooting

Connection Test Fails

  1. Check Server URL: Ensure the URL is correct and accessible
  2. Verify Credentials: Double-check username and password
  3. SSL Certificate: If using self-signed certificate, uncheck "Verify SSL"
  4. Firewall: Ensure your server allows CalDAV connections (usually port 443)

No Events Imported

  1. Check Time Range: Events must be within the lookback period
  2. Verify Calendar URL: Ensure the calendar URL is correct
  3. Check Event Types: Only timed events (not all-day events) are imported
  4. Review Sync Log: Check the integration details page for error messages

Duplicate Events

  • The system prevents duplicates using event UIDs
  • If you see duplicates, they may have different UIDs (rare)
  • Check the integration sync history for details

Limitations

  • One-Way Sync: Currently only imports from calendar to TimeTracker (not bidirectional)
  • Timed Events Only: All-day events are skipped
  • No Recurring Events: Recurring events are imported as individual instances
  • Manual Sync: Automatic sync is not yet implemented (use "Sync Now" button)

Future Enhancements

Planned features:

  • Bidirectional sync (TimeTracker → Calendar)
  • Automatic periodic sync
  • Support for all-day events
  • Better project matching with tags/categories
  • Event updates (modify time entries when calendar events change)

Security Notes

  • Passwords are stored encrypted in the database
  • SSL verification is enabled by default (recommended)
  • Only events from your configured calendar are accessed
  • No calendar data is shared with third parties

Support

For issues or questions:

  1. Check the integration sync history for error messages
  2. Review server logs for connection issues
  3. Test connection using the "Test Connection" button
  4. Contact your system administrator if problems persist
Reference in New Issue View Git Blame Copy Permalink