274 lines
8.2 KiB
Markdown
274 lines
8.2 KiB
Markdown
# CalDAV Plugin Knowledge Base
|
|
|
|
Knowledge base for Leantime's CalDAV integration. Use this to answer user questions about calendar synchronization.
|
|
|
|
## Quick Reference
|
|
|
|
| Attribute | Value |
|
|
|-----------|-------|
|
|
| **Feature** | Bidirectional calendar sync |
|
|
| **Location** | Settings > CalDAV Integration |
|
|
| **Access** | Owner, Admin, Manager, Editor roles |
|
|
| **Sync Frequency** | Real-time + every 15 minutes |
|
|
|
|
---
|
|
|
|
## Common User Questions
|
|
|
|
### "How do I sync my calendar with Leantime?"
|
|
|
|
There are two ways to sync:
|
|
|
|
**Option 1: Use Leantime as a CalDAV Server (Recommended)**
|
|
Connect your phone or desktop calendar app directly to Leantime.
|
|
- Server URL: `https://[your-leantime-url]/caldav/server/`
|
|
- Username: Your Leantime email
|
|
- Password: Your Leantime password
|
|
- Works with: Apple Calendar, Thunderbird, DAVx5, Evolution
|
|
|
|
**Option 2: Push to External Server (Outbound)**
|
|
Push Leantime events to a CalDAV server like Nextcloud.
|
|
1. Go to Settings > CalDAV Integration
|
|
2. Click "Add CalDAV Account"
|
|
3. Enter your Nextcloud/ownCloud calendar URL and credentials
|
|
4. Click Connect
|
|
|
|
---
|
|
|
|
### "Why aren't my events syncing?"
|
|
|
|
Troubleshooting checklist:
|
|
|
|
1. **Is the account enabled?**
|
|
- Go to Settings > CalDAV Integration
|
|
- Verify the account shows "Enabled" (green badge)
|
|
|
|
2. **Try manual sync**
|
|
- Click "Sync Now" button next to the account
|
|
- Check if events appear after sync
|
|
|
|
3. **Check credentials**
|
|
- Edit the account
|
|
- Re-enter the password
|
|
- Save and try again
|
|
|
|
4. **Verify the calendar URL**
|
|
- URLs vary by server type:
|
|
- Nextcloud: `https://server.com/remote.php/dav/calendars/USERNAME/CALENDAR/`
|
|
- Baikal: `https://server.com/dav.php/calendars/USERNAME/CALENDAR/`
|
|
- Radicale: `https://server.com/USERNAME/CALENDAR/`
|
|
|
|
5. **Check SSL settings**
|
|
- If using self-signed certificates, uncheck "Verify SSL" in account settings
|
|
|
|
---
|
|
|
|
### "Can I use Apple Calendar with Leantime?"
|
|
|
|
Yes! Apple Calendar works great with Leantime's CalDAV server.
|
|
|
|
**Setup on Mac:**
|
|
1. Open Calendar > Add Account > Other CalDAV Account
|
|
2. Choose "Manual" for account type
|
|
3. Enter:
|
|
- Username: Your Leantime email
|
|
- Password: Your Leantime password
|
|
- Server: `https://your-leantime-url/caldav/server/`
|
|
4. Click Sign In
|
|
|
|
**Setup on iPhone/iPad:**
|
|
1. Settings > Calendar > Accounts > Add Account
|
|
2. Choose Other > Add CalDAV Account
|
|
3. Enter same details as above
|
|
4. Tap Next
|
|
|
|
---
|
|
|
|
### "Can I use Google Calendar with Leantime?"
|
|
|
|
Google Calendar doesn't support standard CalDAV for third-party apps.
|
|
|
|
**Workarounds:**
|
|
1. Use Nextcloud with Google Calendar integration as a bridge
|
|
2. Export events as ICS and import manually
|
|
3. Use DAVx5 on Android which can sync to multiple calendars
|
|
|
|
---
|
|
|
|
### "What's the difference between Server URL and Calendar URL?"
|
|
|
|
**Server URL**: The base address of the CalDAV server
|
|
- Example: `https://cloud.example.com`
|
|
|
|
**Calendar URL**: The full path to your specific calendar
|
|
- Example: `https://cloud.example.com/remote.php/dav/calendars/john/personal/`
|
|
|
|
Think of it like:
|
|
- Server URL = the building address
|
|
- Calendar URL = the specific room in that building
|
|
|
|
---
|
|
|
|
### "Is my password secure?"
|
|
|
|
Yes. CalDAV passwords are:
|
|
- Encrypted in the database using AES-256-CBC
|
|
- Never stored in plain text
|
|
- Decrypted only when making CalDAV requests
|
|
- Protected by your Leantime installation's APP_KEY
|
|
|
|
For the CalDAV server feature, connections should always use HTTPS to protect credentials in transit.
|
|
|
|
---
|
|
|
|
### "What gets synced?"
|
|
|
|
| Content | Direction | Editable |
|
|
|---------|-----------|----------|
|
|
| Calendar events | Two-way | Yes |
|
|
| All-day events | Two-way | Yes |
|
|
| Ticket due dates | Read-only | No* |
|
|
| Ticket work periods | Read-only | No* |
|
|
|
|
*To change ticket dates, edit the ticket directly in Leantime.
|
|
|
|
---
|
|
|
|
### "How often does sync happen?"
|
|
|
|
- **Immediately**: When you create, edit, or delete an event in Leantime
|
|
- **Every 15 minutes**: Automatic background sync pulls changes from external servers
|
|
- **On demand**: Click "Sync Now" to force immediate sync
|
|
|
|
---
|
|
|
|
### "Why can't I delete ticket due dates from my calendar app?"
|
|
|
|
Ticket due dates appear on your calendar but are "read-only" in external apps. They're controlled by the ticket itself.
|
|
|
|
**To change a ticket's due date:**
|
|
1. Open the ticket in Leantime
|
|
2. Edit the due date field
|
|
3. Save the ticket
|
|
4. The calendar will update automatically
|
|
|
|
---
|
|
|
|
### "How do I see someone else's calendar?"
|
|
|
|
CalDAV sync is personal - each user can only see their own calendar events.
|
|
|
|
**For team visibility:**
|
|
- Use project-level calendars in Leantime
|
|
- Share calendars through your external CalDAV server
|
|
- Use the team calendar view in Leantime
|
|
|
|
---
|
|
|
|
### "My external app can't connect to Leantime"
|
|
|
|
Check these common issues:
|
|
|
|
1. **URL format**: Make sure you're using `https://your-url/caldav/server/` (with trailing slash)
|
|
|
|
2. **Credentials**: Use your Leantime email and password
|
|
|
|
3. **HTTPS**: The CalDAV server requires HTTPS. HTTP connections won't work.
|
|
|
|
4. **Firewall**: Ensure port 443 is open for inbound connections
|
|
|
|
5. **App compatibility**: Some apps need specific setup:
|
|
- Thunderbird needs TbSync add-on
|
|
- Outlook needs CalDav Synchronizer add-on
|
|
|
|
---
|
|
|
|
### "Can I sync with multiple calendars?"
|
|
|
|
**Outbound (to external servers)**: Yes! Add multiple CalDAV accounts in Settings > CalDAV Integration. Each account syncs to a different external calendar.
|
|
|
|
**Inbound (as CalDAV server)**: Leantime exposes one calendar per user containing all their events.
|
|
|
|
---
|
|
|
|
### "Events sync but show wrong times"
|
|
|
|
This is usually a timezone issue:
|
|
|
|
1. Check your Leantime timezone setting (User Settings)
|
|
2. Check your calendar app's timezone
|
|
3. Ensure both are set correctly
|
|
|
|
Leantime stores all times in UTC internally and converts for display.
|
|
|
|
---
|
|
|
|
## Technical Details
|
|
|
|
### Sync Architecture
|
|
|
|
```
|
|
┌─────────────┐ Real-time ┌──────────────┐
|
|
│ Leantime │ ─────────────────> │ External │
|
|
│ Calendar │ │ CalDAV │
|
|
│ Events │ <───────────────── │ Server │
|
|
└─────────────┘ Every 15 min └──────────────┘
|
|
|
|
┌──────────────┐ ┌─────────────┐
|
|
│ External │ ────────────────> │ Leantime │
|
|
│ Calendar │ CalDAV │ CalDAV │
|
|
│ App │ <──────────────── │ Server │
|
|
└──────────────┘ Protocol └─────────────┘
|
|
```
|
|
|
|
### Event Hooks
|
|
|
|
- `afterCalendarSave` - Triggers sync when event created/edited
|
|
- `afterCalendarDelete` - Triggers deletion on external servers
|
|
|
|
### Database Tables
|
|
|
|
- `zp_caldav_accounts` - Stores CalDAV connection settings
|
|
- `zp_caldav_events` - Maps Leantime events to CalDAV UIDs
|
|
|
|
### API Endpoints
|
|
|
|
- `GET /caldav/settings` - Settings page
|
|
- `GET /caldav/connect` - Add account form
|
|
- `POST /caldav/connect` - Save new account
|
|
- `GET /caldav/edit/{id}` - Edit account form
|
|
- `POST /caldav/edit/{id}` - Update account
|
|
- `GET /caldav/delete/{id}` - Delete account
|
|
- `GET /caldav/sync/{id}` - Manual sync trigger
|
|
- `/caldav/server/*` - CalDAV protocol endpoint
|
|
|
|
---
|
|
|
|
## Related Features
|
|
|
|
- **Calendar Module**: View and manage events at `/calendar/showMyCalendar`
|
|
- **Ticket Due Dates**: Set via ticket edit, appear on calendar
|
|
- **Dashboard Widget**: Shows upcoming calendar events
|
|
- **Personal Companion**: Can help schedule and manage time
|
|
|
|
---
|
|
|
|
## Error Messages
|
|
|
|
| Error | Meaning | Solution |
|
|
|-------|---------|----------|
|
|
| "Connection test failed" | Can't reach CalDAV server | Check URL and credentials |
|
|
| "Invalid credentials" | Username/password wrong | Re-enter credentials |
|
|
| "SSL certificate error" | Certificate validation failed | Uncheck "Verify SSL" for self-signed certs |
|
|
| "Calendar not found" | Calendar URL incorrect | Verify calendar URL format |
|
|
| "Sync failed" | Error during sync | Check logs, try manual sync |
|
|
|
|
---
|
|
|
|
## Plugin Information
|
|
|
|
- **Plugin Name**: CalDAV Integration
|
|
- **Location**: `app/Plugins/CalDAV/`
|
|
- **Dependencies**: sabre/dav, sabre/vobject
|
|
- **Documentation**: `CalDAV/docs/README.md`
|