Calendars and contacts over ActiveSync
Poste.io ships two things that, up to 2.5.23, never met:
- Z-Push, the ActiveSync server phones use for the "Exchange" account type, configured for mail only: the phone's calendar and contacts switches are on, but nothing ever arrives;
- a CalDAV/CardDAV server (SabreDAV, at
https://<your host>/dav/) where each mailbox can have calendars and address books, created from the admin.
With one ActiveSync account the phone gets the mail and the calendars and contacts of the DAV server: the same data a CalDAV/CardDAV client sees, both ways. Since 2.5.24 Poste.io connects them itself, with the stock CalDAV and CardDAV backends of Z-Push. This add-on (Poste.io 2.5.24 or later) keeps that and replaces only those two backends with corrected ones: an event refused by the server is not reported to the phone as saved, and the DAV server switched off does not take ActiveSync down (see the issues worked around, below).
What users get
| The mailbox has (in the admin) | The phone shows |
|---|---|
| nothing | mail + the "Calendar" and "Contacts" Poste.io creates for it (see below) |
| a calendar | mail + that calendar (as the default calendar) + its tasks |
| an address book | mail + contacts |
| a calendar shared by a colleague | that calendar as an additional calendar |
Everything goes both ways: an event or a contact created on the phone is stored on the server, and changes on the server reach the phone.
Enabling calendars and contacts for a mailbox
Calendars and address books are created per mailbox from the admin. Since 2.5.24, while DAV is enabled, Poste.io's DAV server also gives a mailbox that has none an empty "Calendar" and "Contacts" at its first DAV access (the webmail calendar, ActiveSync and invitations need somewhere to put things): the add-on cannot and does not prevent it.
- Settings → DAV (Experimental) → Enabled must be ticked (it enables the DAV server itself).
- Mailboxes → the mailbox → DAV section: Create calendar and/or Create address book.
- On the phone, in the ActiveSync account settings, calendar and contacts synchronisation must be on; then sync (or wait for the next sync).
- After switching DAV on or off, restart the container: since 2.5.24 Poste.io chooses the ActiveSync backend (mail only, or mail + calendars and contacts) when the container starts.
A mailbox without a calendar or an address book keeps mail only on the phone. When a calendar or an address book is created or deleted in the admin, the phone adds or removes the folder at its next folder sync.
Seeing whether a colleague is busy: read-only sharing
In the DAV section of the colleague's mailbox, open the calendar's share page, pick the mailbox to share with and choose read only. On that user's phone the colleague's calendar appears as an additional calendar, with the events and their titles (the DAV server has no "free/busy only" level).
Writing in a read-only calendar from the phone is refused: a new event gets an error, a change gets a conflict (the server version wins), a deletion is not applied on the server and the event comes back at the next sync. Read-write sharing works too.
The default calendar
ActiveSync has one default calendar per account. Poste.io names calendars with
random identifiers, so the add-on does not guess: it asks the server through
schedule-default-calendar-URL (RFC 6638), the same property CalDAV clients use
for invitations. SabreDAV answers with the first calendar owned by the
user; calendars shared by colleagues are never the default.
Setting up the phone
Add an Exchange / ActiveSync account with the mailbox address and password and your mail server's host name, then make sure calendar and contacts synchronisation are enabled for that account. Tested with the Gmail app on Android; other ActiveSync clients should behave the same but were not tested.
When the DAV server is off or broken
Z-Push's combined backend refuses the whole login if any of its backends refuses it, so without care a DAV server that does not answer would take ActiveSync down for every user, mail included. The add-on prevents that:
- if, at login, the DAV server does not answer as it should (for example DAV disabled in the settings), the calendar and contacts backends accept the login without folders;
- the phone keeps syncing mail (new mail is delivered in the same reply), and removes calendars and contacts at its next folder sync;
- when the DAV server is back, calendars and contacts come back by themselves.
The Z-Push log then shows the DAV server is not answering ... mail goes on.
Installing on an existing installation: devices must resync
Build and run the image as described in Installation. The add-on changes Z-Push's configuration, and with it the identifiers of the mail folders; a phone that was already syncing would receive the new folders without the old ones being removed (duplicated mail folders). Right after the first start with the add-on, ask every device for a full resync:
# every user/device pair known to Z-Push
docker exec <container> sh -c 'cd /opt/z-push && runuser -u www-data -- php z-push-admin.php -a list'
# one pair (device ids are listed without dashes)
docker exec <container> runuser -u www-data -- php /opt/z-push/z-push-admin.php -a resync -u <user> -d <device>
# or all pairs at once
docker exec <container> sh -c 'cd /opt/z-push && runuser -u www-data -- php z-push-admin.php -a list | awk "NF == 2 && \$1 != \"Device\" && \$1 !~ /^-/" | while read -r d us; do for u in $(echo "$us" | tr , " "); do runuser -u www-data -- php z-push-admin.php -a resync -u "$u" -d "$d"; done; done'
Each phone then starts again from an empty folder list at its next sync (the mail app may need to be opened). Messages stay on the server; the phone only downloads them again.
Rebuilding the image or upgrading Poste.io with the add-on inside does not
need a resync: the configuration stays the same and Z-Push's state lives on
the /data volume (/data/zpush).
Removing the add-on
Remove the ActiveSync: calendars and contacts block from the Dockerfile, rebuild, recreate the container, then resync every device as above (the folder identifiers change back).
Upgrading Poste.io
activesync-dav-install.sh checks every line it changes in Z-Push's
configuration and stops the build if one of them is not exactly as
expected. A Poste.io release that changes Z-Push therefore breaks the build
loudly instead of producing a half-configured image.
Limitations
- Complex recurrences are simplified on the phone (a Z-Push limit): for example "monthly on the 2nd and 3rd" arrives as "monthly on the 2nd". The event on the server is untouched.
- No free/busy lookup when inviting: Z-Push implements it for Kopano only, not for CalDAV. Use read-only sharing to see a colleague's calendar.
- No shared or global address book: Poste.io's DAV server shares calendars, not address books.
- All of a user's address books appear as one contacts folder (Z-Push's CardDAV backend); new contacts from the phone go to the first address book.
- Tasks: Z-Push shows every calendar twice, as events and as tasks.
How it works
Configuration changed by activesync-dav/activesync-dav-install.sh (3 lines in
2 files; each one, and the settings of Poste.io the backends rely on, is
checked before anything is written):
File (in /opt/z-push) |
Change |
|---|---|
config.php |
none: Poste.io sets BACKEND_PROVIDER at every start (BackendCombined while DAV is enabled) |
backend/combined/config.php |
the calendar backend c → BackendPosteCalDAV, the contacts backend d → BackendPosteCardDAV (the folder mapping of Poste.io is kept) |
backend/caldav/config.php |
none: server, port and path are the ones Poste.io writes |
backend/carddav/config.php |
default path /dav/addressbooks/%u/ instead of …/default/: new contacts go to the user's first address book, no "default" one is created |
Files installed in /opt/z-push/backend/:
| File | Role |
|---|---|
postecaldav/postecaldav.php |
BackendPosteCalDAV, extends Z-Push's BackendCalDAV |
postecarddav/postecarddav.php |
BackendPosteCardDAV, extends Z-Push's BackendCardDAV |
postecaldav/postedav.php |
PROPFIND helper shared by both |
Both backends talk to the DAV server inside the container, at the address
Poste.io configures, with the credentials the phone logged in with (HTTP Basic, the mailbox password). Each
login starts with one PROPFIND that is also the health check of the DAV
server. The Debian package libawl-php (needed by Z-Push's CalDAV client) is
part of Poste.io since 2.5.24; the Dockerfile still installs it, harmless, so
the add-on does not depend on it; its directory is appended to PHP's include
path by the backend only.
Z-Push issues worked around
Found while testing Z-Push 2.7.5 against Poste.io's DAV server, and fixed in the two backends without modifying Z-Push's own files:
- An event refused by the server was confirmed to the phone as saved.
BackendCalDAVnever checks the result of the PUT, so an event written in a read-only shared calendar stayed on the phone while nobody else saw it. Now a refused write or deletion is an error for the device. - A contact added by a user without an address book crashed Z-Push (out of memory, HTTP 500 for the whole sync, mail included, retried by the phone forever). Now a user without an address book has no contacts folder, and a contact sent anyway gets an error.
- The DAV server switched off took ActiveSync down, see above.
Troubleshooting
- Z-Push logs:
/var/log/z-push/z-push.logandz-push-error.login the container. The add-on's lines start withBackendPosteCalDAV,BackendPosteCardDAVorPosteDAV. - What a device has:
z-push-admin.php -a list -u <user> -d <device>(run aswww-data, see above) shows the folders and the synchronised data (Emails,Calendars,Tasks,Contacts). - Calendars missing for everybody: check that DAV is enabled in the settings;
with DAV disabled
/dav/answers Enable DAV at your server settings. - Calendars missing for one user: that mailbox has no calendar in the admin, or the phone has calendar sync switched off for the account.
Tested
Poste.io 2.5.24 with Z-Push 2.7.5, Pro (in production) and open source (built and tested in a container). In a test container built from the Dockerfile: folder types and default calendar, server ↔ phone for events and contacts, read-only sharing, users with nothing enabled, an address book removed while the phone still had the folder, DAV switched off and on again, and the migration of an already-synchronised phone with and without the resync.