Page tree
Skip to end of metadata
Go to start of metadata

A static configuration to share folders was added in Z-Push 2.0. Since Z-Push 2.3 it's also possible to open shared folders where the user only has read-only permissions.

This page aims to explain how the shared folder feature works and what you need to know about its internal workings and limitations.


ActiveSync was not designed to "open shared folders" as you know it from collaborative software, where you easily get "a view" with different types of permissions on data of another user or a public folder. ActiveSync is about your data, so you always have your calendars, your contacts and your emails etc on your mobile.

As all data known by ActiveSync is yours, there will never be any permission restriction: you can always do everything with your data: create, delete and modify. Everything! The mobiles or the ActiveSync protocol do not cover the case that you might lack permissions (because by the above definition you can't).

Permission issue

Sharing of course causes a permissions' issue. Synchronizing a folder where you lack write permission creates inconsistent syncs quite easily.

If you share a readonly contact folder and create a new contact there on your phone, the server will not be able to save it (due to missing write permissions). For the mobile there is no reason why you shouldn't be allowed to create it. The mobile itself allows it and your sync will be broken instantly: there is new data on your phone that will never be saved on the server. Your phone will get an error but will just retry. As there is no error code for "you don't have permissions" your phone will just retry. Forever.

Ultimately your data will be lost, because at some point that folder will be re-synchronized (too many errors) and the data will be lost. This scenario is the worst possible user experience: real data loss!

This is why in the first implementations of the "sharing feature" (Z-Push 2.0) it was required that only folders where the user has at least "secretary permissions" can be shared. This way we ensured that the server will always be able to save any changes coming from your phone and you don't run into the described scenario.

How we share

The only trick here is that we tell the mobile that "there is another folder to be synchronized". For your phone that folder will look and behave like one of your own. It will be displayed together with the other folders with your data and you handle it like one of your own (not all mobiles support that well, e.g. different contact folders are not clearly separated on Android phones).

When something happens in that folder, either on the server or on your phone, Z-Push will just perform a storage switch for this folder, to get or save data in the folder of the other user.

For the static configuration of folders as in Z-Push 2.0+ the permissions are verified during the hierarchy synchronization (FolderSync command). If you have permissions, the folder will be added to your client. If you e.g. lose the permissions the folder will be removed from your phone. 

Shared folders in the configuration file are applied to all users of a system.

Please, read-only support!

But still, there are many use-cases where only read-only permissions are required. You need to see e.g. the public holiday calendar on your mobile client, but you are not allowed to create/move appointments there. 

There is no excellent way to make that happen, as explained, because ActiveSync clients were not made to have limitations on folders and data. We had to solve that on the server side. We detect when you try to write to a folder you don't have permissions and "undo" your change.

This happens in several steps.

1. Should a folder be synchronized to the mobile?

The first decision to make is, if the folder should be synchronized at all to the mobile of a user.

This check is done by checking if you have AT LEAST read permissions on that folder. If you have read permissions, you can synchronize its contents.

User that have not even read permissions will just not see the folder. This is the same it was before.

2. Data to be synchronized

This is the same as in the previous case, if you have read permissions (which you of course need at least) the data will be sent to your phone. No magic here, you have permission to read, you will get the data synchronized.

3. Changes in the shared folder

Now we are at the point where the permissions become crucial. 

The most important thing: If the user HAS WRITE PERMISSION he WILL BE able to WRITE.

The moment we try to write the data (to synchronize actually) is the one that counts. If the user has write permission, changed data will be saved! 

No permissions

But, if the user has no permissions, how to "get rid" of the inconsistent data? The only way is to remove/undo the changes on the client. If a user changes an entry on the client the data will be dropped and be replaced with the original data from the server. The changes are basically undone. If a new item is created, e.g. a new contact, that contact is deleted from the phone while synchronizing. This is the only way to keep it consistent. 

To minimize the impact on data loss, an email will be send to the user alerting that the operation is not permitted. The data of the changed/created item will be stated in the email so the user does not lose this information completely. Changing the first name in a read only contact folder will be communicated to the user like this:

Dear User,

on 26.04.2016 at 14:06:55 you've tried to save a data in the folder 'Public Contacts' on your device 'iPhone' ID: 'Appl888asdxxasdqq9'.
This operation was not successful, as you lack write access to this folder.
Your data has been dropped and replaced with the original data on your device to ensure data integrity.

Below the data you tried to save. You should seek other means to it (e.g. forward this email to a person with write access to this folder).

Object type: Contact
Companyname:             FCB
Fileas:                  Neuer, Manoel
Firstname:               Manoel - Your data: Manuel
Jobtitle:                Keeper
Lastname:                Neuer

If you have questions about this email, please contact your e-mail administrator.

Your Z-Push system

The template of this email can be edited in the Kopano configuration file. Sending this email could also be disabled, but this is highly discouraged, as real data loss will happen and the user will not know about it.

Corner case - moving items

There are a few other issues supporting read only folders, like what should happen when moving items, e.g. an email from one folder into another.

If a folder where the user has not full permissions (write permission) is involved, the operation will be undone as well. The email will be restored in the source folder and be removed from the destination folder. About this operation no email is generated for the user.

This applies when moving from or to such a folder.


The options to add shared folders is available in the configuration file for global setup. Please have a look at the description above the corresponding config section for the configuration steps. Since Z-Push 2.3 it's also possible to add shared folders per device level, currently available only via the Webservice. In the future there will be more convenient ways of doing this, e.g. directly from WebApp/DeskApp or in Outlook via the Configuring GAB-Sync for Kopano OL Extension.

  • No labels