Z-push 2.1

From Group-Office Groupware and CRM Documentation
(Redirected from Z-push 2)
Jump to: navigation, search

Overview

This module can be used to synchronize Emails, Contacts, Tasks and Calendars to a mobile device/tablet.

Dependencies

Apache modules

Some apache modules cannot be enabled because Z-Push is NOT working when they are enabled.

Requirements

  1. Works on a Linux or Mac (POSIX) server only. It does not work on a Windows server.

Installation

Automatic

To install the z-push module automatically, you can use the script that is provided with the "Sync" module. (install.sh)

The script is located in the "modules/sync/z-push" folder.

Manual

ActiveSync support does not work out of the box. We use the third party library z-push. To add support of ActiveSync take the following steps (Step 1 to 5 can be done with modules/sync/z-push/install.sh too):

1. Download z-push from http://zarafa-deutschland.de/z-push-download/final/2.1/. We used version 2.1.3-1892 (But it's probably best to take the latest stable 2.1.x version of z-push).

2. Unpack the archive and put it in the "modules" directory of Group-Office.

3. rename the folder to "z-push"

4. Copy the folder modules/sync/z-push/backend/go/ to modules/z-push/backend/

5. Copy modules/sync/z-push/config.php to modules/z-push/config.php

6. Now, you must configure Apache to redirect the URL 'Microsoft-Server-ActiveSync' to the index.php file in the modules/z-push/ directory.
This can be done by adding the line:

Alias /Microsoft-Server-ActiveSync /path/to/groupoffice/modules/z-push/index.php

Don't use a symlink, this won't work.

7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync!

Known issues per device

Device OS Issue
Iphone All IOS versions Removing participant from a recurring event on the phone that will be saved as an exception event will also delete the participants on the main event
IOS 7 New tasklists that are created on the device will not be synced to Group-Office. The list will be kept on the phone but the tasks itself will also be added to the main tasklist.
HTC HERO (maybe more) Contacts that are synced to the phone and then marked as favorite on the phone will add HTC xml data to the comments field.

CGI mode

By default z-push only works when PHP is loaded as an Apache module. If you use PHP in CGI mode you'll have to add 2 .htaccess files

One you have to put in /modules/z-push/.htaccess:

RewriteEngine on
RewriteRule .* - [E=HTTP_MS_ASPROTOCOLVERSION:%{HTTP:Ms-Asprotocolversion}]
RewriteRule .* - [E=HTTP_X_MS_POLICYKEY:%{HTTP:X-Ms-Policykey}]
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

Below you can find an example .htaccess file that needs to be placed in the Group-Office document root(next to the index.php file):

Options +FollowSymLinks
RewriteEngine On

#Mind the absolute path to index.php here. On shared hosts you can often find it in config.php  ($config['root_path']).
RewriteRule Microsoft-Server-ActiveSync(.*) /var/www/groupoffice/modules/z-push/index.php$1 [E=ACTIVESYNC:true,E=REMOTE_USER:%{HTTP:Authorization}]

Note: Change the path to Group-Office to the correct absolute path for your server.

Uninstall

Remove the z-push folder from the modules directory of Group-Office and remove the apache alias that is described above.

User Manual

Visit the following page for client instructions:

Synchronization

Additional Notes

For debugging change modules/z-push/config.php:

define('LOGLEVEL', LOGLEVEL_ALL);

A log will be generated in /home/groupoffice/log/

Z-Push can only sync email when running on a default HTTP port eg. 80 or 443

Debugging

When the synchronization is not working at all, then please check if the following url is working:

http(s)://{your_go_base_url}/Microsoft-Server-ActiveSync

That url should pop-up a login dialog in which you'll need to fill in your GO username and password.

After logging in a webpage should become visible with some z-push version info text and the following line on it: GET not supported

When you see that line, then the configuration of z-push should be correct.


If one of the described steps does not work then you'll need to check your server configuration. Then please check the following things:

  • Check if the alias: /Microsoft-Server-ActiveSync is pointing to the "{GO}/modules/z-push" folder.
  • Check your login credentials.
  • If you are using the z-push admin module, please check the setting of that module. There is a setting in where you can manage if connections are authorized by default.


Sometimes it can happen that an item is not synced to the device, then you can make a log file for that specific user.

Creating a synchronization log file

When the synchronization is not working anymore for a user, then you can create a logfile of the synchronization of that particular user.

You can enable this by adding the following configuration variable to the Group-Office config.php file.

$config['zpush2_special_log_users']=array('username','username2');

After you have done that, a log file with the name: {username}.log will be created on the following location: {go_file_storage_path}/log/z-push/

Sometimes you can find more information about the synchronization problem in that log.

If you don't understand what's happening then you can create a ticket at our ticketsystem. Please add the generated logfile to the ticket so we have some debug information.

  • Don't forget to remove the users from the GO configuration variable after the log is created so the logfiles will not grow to huge files anymore.

Z-Push admin commandline tool

When you get an error in the "z-push-error.log" file that is located in the {go_file_storage_path}/log/z-push/ folder.

The error can look like this:

01/02/2013 12:22:31 [24372] [ERROR] [john@doe.com] Ignored broken message (SyncAppointment). Reason: '4' Folderid: 'a/GroupOfficeCalendar' message id '25'
01/02/2013 12:33:53 [28717] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674'
01/02/2013 12:34:02 [28717] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674'
01/02/2013 12:36:35 [13733] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674'

When this happens you can usually find more info on this error by using the "z-push-admin.php" file that is located in the z-push folder.

This is a commandline tool that is shipped with the z-push2.1 package.

You can use it like this:

cd /usr/share/groupoffice/modules/z-push
php z-push-admin.php -a list -u {go_username}
  • Note: You need to go to the directory of z-push first because otherwise the GO config file cannot be loaded.

If the config file still cannot be found then add this line directly after the <?php open tag in the z-push-admin.php file:

define('GO_CONFIG_FILE',{absolute_path_to_config_file});

When you have ran the z-push-admin tool then you can find a better error description for each device in the result of the "list" command.

Ignored broken message

When this happens there could be 3 reasons.

  1. the object is broken in whatever reason (detected by Z-Push, semantic error, like appointments end date is before the start date)
  2. there is a connection issue between the server and the mobile (bad reception, network instabilities etc.)
  3. the mobile can (for whatever reason) not process the received data

Check Start menu -> ActiveSync management and select your device to find more information. It might help to resync your device. Double click the device and click the "Resync" button. If the problem persists then submit a support ticket and include a complete log file (see Z-push_2.1#Creating_a_synchronisation_log_file).