1# �� DokuWiki → Outlook Sync Setup Guide 2 3## �� Prerequisites 4 5- PHP 7.4+ with cURL extension 6- Office 365 / Outlook.com account 7- Azure account (free tier works fine) 8 9--- 10 11## �� Step 1: Azure App Registration 12 13### 1. Go to Azure Portal 14https://portal.azure.com → **Azure Active Directory** → **App registrations** 15 16### 2. Create New Registration 17- Click **"New registration"** 18- Name: `DokuWiki Calendar Sync` 19- Supported account types: **"Accounts in this organizational directory only"** 20- Redirect URI: Leave blank 21- Click **Register** 22 23### 3. Note Your IDs 24**Copy these values** (you'll need them): 25- **Application (client) ID** - e.g., `abc123-...` 26- **Directory (tenant) ID** - e.g., `xyz789-...` 27 28### 4. Create Client Secret 29- Go to **Certificates & secrets** tab 30- Click **"New client secret"** 31- Description: `DokuWiki Sync` 32- Expires: **24 months** (recommended) 33- Click **Add** 34- **⚠️ COPY THE SECRET VALUE NOW** - You can't see it again! 35 36### 5. Grant API Permissions 37- Go to **API permissions** tab 38- Click **"Add a permission"** 39- Choose **Microsoft Graph** 40- Choose **Application permissions** 41- Search and add: 42 - `Calendars.ReadWrite` ✅ 43 - `User.Read.All` ✅ 44- Click **"Grant admin consent"** (requires admin) 45 - If you're not admin, request consent from IT 46 47--- 48 49## ⚙️ Step 2: Configure Sync Script 50 51### 1. Edit Configuration File 52```bash 53cd /var/www/html/dokuwiki/lib/plugins/calendar 54nano sync_config.php 55``` 56 57### 2. Fill In Credentials 58```php 59'tenant_id' => 'YOUR_TENANT_ID_HERE', // From Azure Portal 60'client_id' => 'YOUR_CLIENT_ID_HERE', // Application ID 61'client_secret' => 'YOUR_CLIENT_SECRET_HERE', // Secret value 62'user_email' => 'your@email.com', // Your Office 365 email 63``` 64 65### 3. Configure Category Mapping (Optional) 66Map DokuWiki namespaces to Outlook categories: 67```php 68'category_mapping' => [ 69 'work' => 'Blue category', 70 'personal' => 'Green category', 71 'projects' => 'Yellow category', 72], 73``` 74 75**Available Outlook Categories:** 76- Blue category 77- Green category 78- Orange category 79- Red category 80- Yellow category 81- Purple category 82 83### 4. Save Configuration 84```bash 85# Make sure permissions are secure 86chmod 600 sync_config.php 87``` 88 89--- 90 91## �� Step 3: Test the Sync 92 93### 1. Dry Run (No Changes) 94```bash 95php sync_outlook.php --dry-run 96``` 97 98**Expected output:** 99``` 100[2026-01-25 23:45:30] [INFO] === DokuWiki → Outlook Sync Started === 101[2026-01-25 23:45:30] [INFO] DRY RUN MODE - No changes will be made 102[2026-01-25 23:45:31] [INFO] Authenticating with Microsoft Graph API... 103[2026-01-25 23:45:32] [INFO] Authentication successful 104[2026-01-25 23:45:32] [INFO] Loading DokuWiki calendar events... 105[2026-01-25 23:45:32] [INFO] Found 25 events in DokuWiki 106[2026-01-25 23:45:32] [INFO] Created: Meeting [work] 107[2026-01-25 23:45:32] [INFO] Created: Dentist [personal] 108... 109[2026-01-25 23:45:35] [INFO] === Sync Complete === 110[2026-01-25 23:45:35] [INFO] Scanned: 25 events 111[2026-01-25 23:45:35] [INFO] Created: 25 112[2026-01-25 23:45:35] [INFO] Updated: 0 113[2026-01-25 23:45:35] [INFO] Deleted: 0 114``` 115 116### 2. Real Sync 117If dry run looks good: 118```bash 119php sync_outlook.php 120``` 121 122### 3. Check Outlook 123Open Outlook and verify: 124- Events appear in your calendar 125- Categories are color-coded 126- Reminders are set (15 minutes before) 127 128--- 129 130## �� Step 4: Automate with Cron 131 132### 1. Add Cron Job 133```bash 134crontab -e 135``` 136 137### 2. Add This Line 138```bash 139# Sync DokuWiki calendar to Outlook every 30 minutes 140*/30 * * * * cd /var/www/html/dokuwiki/lib/plugins/calendar && php sync_outlook.php >> sync.log 2>&1 141``` 142 143### 3. Alternative: Hourly Sync 144```bash 145# Every hour at :15 (e.g., 1:15, 2:15, 3:15) 14615 * * * * cd /var/www/html/dokuwiki/lib/plugins/calendar && php sync_outlook.php >> sync.log 2>&1 147``` 148 149--- 150 151## �� Usage Examples 152 153### Sync Everything 154```bash 155php sync_outlook.php 156``` 157 158### Sync Specific Namespace 159```bash 160php sync_outlook.php --namespace=work 161``` 162 163### Dry Run (Preview Changes) 164```bash 165php sync_outlook.php --dry-run 166``` 167 168### Force Re-sync All 169```bash 170php sync_outlook.php --force 171``` 172 173### Verbose Output 174```bash 175php sync_outlook.php --verbose 176``` 177 178--- 179 180## �� Files Created 181 182- **sync_config.php** - Your credentials (gitignore this!) 183- **sync_state.json** - Mapping of DokuWiki IDs to Outlook IDs 184- **sync.log** - Sync history and errors 185 186--- 187 188## �� Troubleshooting 189 190### "Failed to get access token" 191- Check your tenant_id, client_id, and client_secret 192- Verify API permissions are granted in Azure 193- Check if client secret has expired 194 195### "Calendars.ReadWrite permission not granted" 196- Go to Azure Portal → App registrations → Your app → API permissions 197- Click "Grant admin consent" 198- May need IT admin to approve 199 200### Events not syncing 201```bash 202# Check the log 203tail -f sync.log 204 205# Test authentication 206php sync_outlook.php --dry-run --verbose 207``` 208 209### Wrong timezone 210```bash 211# Edit sync_config.php 212'timezone' => 'America/Los_Angeles' # Pacific Time 213'timezone' => 'America/New_York' # Eastern Time 214'timezone' => 'Europe/London' # GMT 215``` 216 217### Categories not showing 218- Categories must exist in Outlook first 219- Use one of the 6 preset colors 220- Or create custom categories in Outlook settings 221 222--- 223 224## �� Category Setup in Outlook 225 226### Option 1: Use Presets (Easiest) 227Just use the built-in colors: 228- Blue category 229- Green category 230- Yellow category 231- Orange category 232- Red category 233- Purple category 234 235### Option 2: Rename Categories 2361. Open Outlook 2372. Go to **Calendar** view 2383. Right-click any category 2394. Choose **"All Categories"** 2405. Rename categories to match your namespaces: 241 - Blue category → Work 242 - Green category → Personal 243 - Yellow category → Projects 244 245Then update sync_config.php: 246```php 247'category_mapping' => [ 248 'work' => 'Work', 249 'personal' => 'Personal', 250 'projects' => 'Projects', 251], 252``` 253 254--- 255 256## �� Security Notes 257 258- **Never commit sync_config.php** to git 259- Add to .gitignore: 260 ``` 261 sync_config.php 262 sync_state.json 263 sync.log 264 ``` 265- File permissions: `chmod 600 sync_config.php` 266- Store credentials securely 267 268--- 269 270## �� What Gets Synced 271 272✅ Event title 273✅ Date and time 274✅ Multi-day events 275✅ All-day events 276✅ Description 277✅ Category (based on namespace) 278✅ Reminders (15 min before) 279 280❌ Recurring events (expanded as individual occurrences) 281❌ Event colors (uses categories instead) 282❌ Task checkboxes (syncs as events) 283 284--- 285 286## �� Advanced Features 287 288### Skip Completed Tasks 289```php 290'sync_completed_tasks' => false, 291``` 292 293### Disable Deletions 294```php 295'delete_outlook_events' => false, 296``` 297 298### Custom Reminder Time 299```php 300'reminder_minutes' => 30, // 30 minutes before 301``` 302 303### Filter Namespaces 304```bash 305# Only sync work events 306php sync_outlook.php --namespace=work 307``` 308 309--- 310 311## �� Pro Tips 312 3131. **Run dry-run first** - Always test with `--dry-run` before real sync 3142. **Check logs** - Monitor `sync.log` for errors 3153. **Backup Outlook** - Export calendar before first sync 3164. **Test with one namespace** - Start small with `--namespace=test` 3175. **Schedule during off-hours** - Run cron at night to avoid conflicts 318 319--- 320 321## �� Support 322 323**Common Issues:** 324- Check sync.log for detailed errors 325- Verify Azure permissions are granted 326- Test API credentials with --dry-run 327- Ensure PHP has cURL extension 328 329**Reset Sync State:** 330```bash 331# Start fresh (will re-sync everything) 332rm sync_state.json 333php sync_outlook.php --dry-run 334``` 335 336--- 337 338**Version:** 1.0 339**Compatibility:** DokuWiki Calendar Plugin v3.3+ 340**Tested:** Office 365, Outlook.com 341 342�� **Happy Syncing!** �� 343