97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# ViaVox
|
||
|
||
Sync Microsoft 365 calendar (and soon contacts) into Nextcloud.
|
||
|
||
ViaVox is the Nextcloud companion app for the **ViaVox Syncer** service: a
|
||
webhook-based Microsoft Graph → Nextcloud CalDAV bridge that keeps Outlook /
|
||
Exchange Online calendars in sync with each Nextcloud user's personal
|
||
calendar, both directions, in near-real-time.
|
||
|
||
This repo distributes the **Nextcloud app** half of the stack. The companion
|
||
syncer service is deployed separately (admins configure its URL + shared
|
||
token).
|
||
|
||
## What it does
|
||
|
||
- Each Nextcloud user can connect / disconnect their own Microsoft 365
|
||
account from **Settings → Personal → ViaVox**.
|
||
- Once connected, Outlook events flow into the user's personal calendar via
|
||
webhook notifications (no polling), and edits made in Nextcloud Calendar
|
||
flow back to Outlook.
|
||
- Recurring meetings — including exceptions, cancellations, DST transitions,
|
||
attendees and RSVPs — are handled end-to-end.
|
||
- **Duplicate cleanup**: surfaces meetings that Exchange minted twice (a fresh
|
||
`vCal-Uid` per iTip round-trip, e.g. when a room is added to an existing
|
||
meeting) and lets the user remove a copy. The delete is fail-closed and
|
||
provenance-gated — only offered when every copy is provably a Microsoft 365
|
||
item — with a per-user lock against concurrent deletes.
|
||
- An admin overview shows per-user connection status and sync health, plus an
|
||
hourly watcher that notifies a user (bell + optional email) if their sync
|
||
goes offline.
|
||
|
||
## Nextcloud scheduling / iTip is deliberately turned off
|
||
|
||
Microsoft 365 is the authoritative scheduler for connected users. If Nextcloud
|
||
*also* ran its own iTip scheduling, every cross-user meeting would get a second,
|
||
NC-minted copy and duplicate invitation emails would go out. ViaVox therefore
|
||
suppresses Nextcloud's built-in calendar scheduling on three layers:
|
||
|
||
1. **No iTip emails** — a repair step sets `dav.sendInvitations=no` on install
|
||
and after every migration, so Nextcloud never emails iTip
|
||
invitations/cancellations for connected users.
|
||
2. **No iTip on the CalDAV path** — a Sabre plugin sets `x-nc-scheduling: false`
|
||
on every calendar-object `PUT`/`DELETE`, short-circuiting Nextcloud's
|
||
scheduler. This also prevents the 403 ("event cannot be deleted") that NC's
|
||
scheduler raises when a room/resource attendee is involved.
|
||
3. **No iTip on internal paths** — a listener covers the internal
|
||
`ICreateFromString` paths (Talk-scheduled meetings, Calendar bookings /
|
||
proposals) that bypass the standard CalDAV route.
|
||
|
||
Microsoft 365 owns invitations and cancellations end to end; Nextcloud mirrors
|
||
the result without generating its own scheduling traffic.
|
||
|
||
## Install
|
||
|
||
1. **Download** the latest `viavox-X.Y.Z.tgz` release asset (see the
|
||
**Releases** page).
|
||
2. Extract into your Nextcloud installation's `apps/` directory so that
|
||
`apps/viavox/appinfo/info.xml` exists:
|
||
|
||
```bash
|
||
tar xzf viavox-0.8.22.tar.gz -C /var/www/nextcloud/apps/
|
||
chown -R www-data:www-data /var/www/nextcloud/apps/viavox
|
||
```
|
||
|
||
3. Enable the app:
|
||
|
||
```bash
|
||
occ app:enable viavox
|
||
```
|
||
|
||
4. As an admin, open **Settings → Administration → ViaVox**, enter the
|
||
ViaVox Syncer base URL and shared NC-app token, hit *Save* and then
|
||
*Test connection*.
|
||
5. Each user can now open **Settings → Personal → ViaVox** and click
|
||
*Connect Microsoft 365* to start syncing.
|
||
|
||
## Requirements
|
||
|
||
- Nextcloud 32 – 34 (verified compatible with Nextcloud 34).
|
||
- PHP 8.1 – 8.4.
|
||
- A reachable ViaVox Syncer instance (separately deployed).
|
||
- A Microsoft 365 tenant with an App Registration that has
|
||
`Calendars.ReadWrite` delegated permission.
|
||
|
||
> **Operator note:** keep `dav calendarRetentionObligation` unset (the default)
|
||
> while the duplicate-cleanup feature is in use, so a removed copy stays
|
||
> restorable from the Nextcloud trash bin.
|
||
|
||
## License
|
||
|
||
AGPL-3.0-or-later. See `COPYING` inside the package.
|
||
|
||
## Support
|
||
|
||
For installation help or to report issues, contact the maintainer (see
|
||
`appinfo/info.xml` for the e-mail address).
|