This manual is deprecated. Please visit https://groupoffice.readthedocs.io for the latest documentation.

Difference between revisions of "Z-push"

From Group-Office Groupware and CRM Documentation
Jump to: navigation, search
(→‎Additional Notes)
(→‎Manual)
 
(10 intermediate revisions by 2 users not shown)
Line 11: Line 11:
 
=Requirements=
 
=Requirements=
  
−
=Installation=
+
#Works on a Linux or Mac (POSIX) server only. It does not work on a Windows server.
  
−
IMPORTANT NOTE: remember to replace the z-push files again when you are upgrading Group-Office if you installed Group-Office manually! Debian packages will do this automatically for you from now on. But you need to perform step 5 manually (this can not be automated due to licensing issues with z-push).
+
=Installation=
  
 
==Automatic==
 
==Automatic==
Line 20: Line 20:
  
 
The script is located in the "modules/sync/z-push" folder.
 
The script is located in the "modules/sync/z-push" folder.
−
 
−
The default alias in /etc/apache2/conf.d/groupoffice.conf points to the "z-push2" folder. Please change it to "z-push".
 
  
 
==Manual==
 
==Manual==
  
−
ActiveSync support does not work out of the box. To add support of ActiveSync
+
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):
−
take the following steps (Step 1 to 5 can be done with modules/sync/z-push2/install.sh too):
+
  
−
1. Download z-push from http://zarafa-deutschland.de/z-push-download/final/1.5/. We used version 1.5.2 (But it's probably best to take the latest stable 1.x version of z-push).
+
1. Download z-push from http://download.z-push.org/final/. We've tested up to version 2.3.4beta.
  
 
2. Unpack the archive and put it in the "modules" directory of Group-Office.
 
2. Unpack the archive and put it in the "modules" directory of Group-Office.
Line 34: Line 31:
 
3. rename the folder to "z-push"  
 
3. rename the folder to "z-push"  
  
−
4. Copy the file backend/GObackend.php from modules/sync/z-push/ to modules/z-push/backend/
+
4. Copy the folder modules/'''sync'''/z-push/backend/go/ to modules/z-push/backend/
  
−
5. Copy config.php from modules/sync/z-push/ to modules/z-push/
+
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.<br />This can be done by adding the line:
 
6. Now, you must configure Apache to redirect the URL 'Microsoft-Server-ActiveSync' to the index.php file in the modules/z-push/ directory.<br />This can be done by adding the line:
Line 45: Line 42:
  
 
7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync!
 
7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync!
 +
 +
===Known issues per device===
 +
{| class="wikitable" style="width:100%;"
 +
|-
 +
! 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==
 
==CGI mode==
 
By default z-push only works when PHP is loaded as an Apache module. If you use
 
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 follow this workaround:
+
PHP in CGI mode you'll have to add 2 .htaccess files
  
−
http://z-push.sourceforge.net/phpbb/viewtopic.php?f=4&t=1245&p=4762&hilit=apache_request_headers#p4762
+
One you have to put in /modules/z-push/.htaccess:
−
 
+
−
You can also try to create a .htaccess file in the Group-Office root dir and add the following lines to it:
+
  
 
<pre>
 
<pre>
−
Options +FollowSymLinks
+
RewriteEngine on
−
RewriteEngine On
+
RewriteRule .* - [E=HTTP_MS_ASPROTOCOLVERSION:%{HTTP:Ms-Asprotocolversion}]
−
RewriteRule /Microsoft-Server-ActiveSync(.*) modules/z-push/index.php$1 [E=ACTIVESYNC:true,E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
+
RewriteRule .* - [E=HTTP_X_MS_POLICYKEY:%{HTTP:X-Ms-Policykey}]
 +
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
 
</pre>
 
</pre>
  
−
In some versionw of PHP the apache_request_header() function doesn't exist and the following needs to be added to modules/z-push/compat.php at the end of the file just before: ?>
+
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):
  
 
<pre>
 
<pre>
−
if (!function_exists('apache_request_headers')) {
+
Options +FollowSymLinks
−
    function apache_request_headers() {
+
RewriteEngine On
−
        $header = array();
+
−
        $header['Ms-Asprotocolversion'] = $_SERVER['HTTP_MS_ASPROTOCOLVERSION'];
+
−
        $header['X-Ms-Policykey'] = $_SERVER['HTTP_X_MS_POLICYKEY'];
+
−
        $header['User-Agent'] = $_SERVER['HTTP_USER_AGENT'];
+
  
−
        return $header;
+
#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}]
−
   
+
−
    list($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']) = explode(':' , base64_decode(substr($_SERVER['REDIRECT_HTTP_AUTHORIZATION'], 6)));
+
−
}
+
 
</pre>
 
</pre>
 +
 +
'''Note:''' Change the path to Group-Office to the correct absolute path for your server.
  
 
=Uninstall=
 
=Uninstall=
  
−
Remove the z-push folder from the modules directory of Group-Office.
+
Remove the z-push folder from the modules directory of Group-Office and remove the apache alias that is described above.
  
 
=User Manual=
 
=User Manual=
  
−
*LINK TO USERMANUAL
+
Visit the following page for client instructions:
 +
 
 +
[[Synchronization]]
  
 
=Additional Notes=
 
=Additional Notes=
  
−
For debugging put a debug.txt file with write permissions in the modules/z-push folder.
+
For debugging change modules/z-push/config.php:
  
−
=Debugging=
+
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=
 
Sometimes it can happen that an item is not synced to the device.  
 
Sometimes it can happen that an item is not synced to the device.  
  
−
Then you can add a file (call the file "debug.txt") to the /modules/z-push folder and make sure that it is writable for Apache.
+
==Creating a synchronisation log file==
 +
When the synchronisation is not working anymore for a user, then you can create a logfile of the synchronisation of that particular user.
 +
 
 +
You can enable this by adding the following configuration variable to the Group-Office config.php file.
 +
<pre>
 +
$config['zpush2_special_log_users']=array('username','username2');
 +
</pre>
 +
 
 +
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 synchronisation 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:
 +
<pre>
 +
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'
 +
</pre>
 +
 
 +
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:
 +
<pre>
 +
cd /usr/share/groupoffice/modules/z-push
 +
php z-push-admin.php -a list -u {go_username}
 +
</pre>
 +
*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:
 +
<pre>
 +
define('GO_CONFIG_FILE',{absolute_path_to_config_file});
 +
</pre>
 +
 
 +
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==
  
−
This log will be filled with debugging information when you sync.
+
When this happens there could be 3 reasons.
  
−
Then try to sync your device again and check the errors in the "debug.txt" file.
+
#the object is broken in whatever reason (detected by Z-Push, semantic error, like appointments end date is before the start date)
 +
#there is a connection issue between the server and the mobile (bad reception, network instabilities etc.)
 +
#the mobile can (for whatever reason) not process the received data
  
−
If you cannot solve the problems by yourself then please create a support ticket for the problem and attach the log to the ticket.
+
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]]).

Latest revision as of 13:57, 20 December 2016

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://download.z-push.org/final/. We've tested up to version 2.3.4beta.

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

Sometimes it can happen that an item is not synced to the device.

Creating a synchronisation log file

When the synchronisation is not working anymore for a user, then you can create a logfile of the synchronisation 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 synchronisation 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).

Retrieved from "http://www.group-office.com/w/index.php?title=Z-push&oldid=4031"