© 2024 by Synacor, Inc. Zimbra Connector for Microsoft Outlook Administration Guide

All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. Zimbra is a registered trademark of Synacor, Inc. in the United States and other jurisdictions. You may not alter or remove any trademark, copyright, or other notice from copies of the content. All other marks and names mentioned herein may be trademarks of their respective companies.

Synacor, Inc.
505 Ellicott Street, Suite A39
Buffalo, New York 14203

1. About ZCO

The Zimbra Connector for Microsoft Outlook® (ZCO) allows users to access and manage their Zimbra Collaboration account using Microsoft Outlook.

Microsoft Outlook speaks a language called MAPI (Messaging Application Programming Interface) and ZCO acts as a translation layer converting Outlook’s MAPI calls into calls the Zimbra Server can understand.

ZCO creates a copy of the account data on the user’s computer in a file called a ZDB so that Outlook can be used even when a connection to the server is not available. ZCO then uses a synchronization mechanism to keep that data synchronized with the server copy. Items that are synchronized include email messages, folders, tags, contacts, personal calendars, appointment reminders, and tasks.

On the server, messaging items are stored in MIME format. In the ZDB, they are stored in MAPI format. ZCO converts between these two formats.

In addition, ZCO allows users to make use of Zimbra sharing and delegation features.

This chapter includes information on the prerequisites for installing ZCO and how to download the ZCO installation file.

ZCO Version Compatibility with Zimbra Collaboration

ZCO is backwards-compatible with supported Zimbra Collaboration versions within the same major release. It is recommended to use the latest version of ZCO to benefit from recent functional and security updates. For example, the latest ZCO 8.x.x version should be used with any Zimbra Collaboration 8.x.x.

Supported Versions of Microsoft Windows®

ZCO is supported on the following Microsoft Operating Systems:

  • Windows 10

  • Windows 11

All operating systems must have the latest updates from Microsoft.

Supported Versions of Microsoft Outlook®

ZCO is supported on the following versions of Microsoft Outlook:

  • Outlook 2021: 32-bit and 64-bit editions of Microsoft Office, including Click to run.

  • Outlook 2019: 32-bit and 64-bit editions of Microsoft Office, including Click to run.

  • Outlook 2016: 32-bit and 64-bit editions of Microsoft Office, including Office365 and Click to run versions. and Click to run versions.

All installations of Microsoft Outlook and Microsoft Office must have the latest updates from Microsoft.

ZCO Files

ZCO comprises the following 3 files. The first is for use by end users, the other two are for use by you, the administrator:

ZimbraConnectorOLK_<version>.msi

This is the main ZCO MSI installer. Available in 32-bit and 64-bit versions, each in signed and unsigned variants. The unsigned versions are for use in MSI customization and branding.

ZmCustomizeMsi.js

The ZCO MSI Customizer. Allows the ZCO MSIs to be customized so that when the user installs ZCO, it automatically pre-sets certain options such as the server name when the user creates a new Outlook profile.

ZimbraBrandMsi.vbs

The ZCO Branding MSI Customizer. This allows the MSIs to be branded. Branding replaces all instances of the Zimbra product name and logo with those of your company.

For information on MSI customization and branding see the chapter Customizing the Installer.

Location of the ZCO Files

The ZCO files are located on the Zimbra Collaboration server in:

/opt/zimbra/jetty-distribution-<version>/webapps/zimbra/downloads/ZimbraConnectorOLK_<version>.msi

Zimbra periodically releases updates for ZCO via https://www.zimbra.com/downloads/zimbra-connector-for-outlook/. You can download these and use

Zimbra administration consoleTools and MigrationClient Upload

to upload the latest version of ZCO to the above location.

How Users Obtain the ZCO MSI

New users typically obtain the ZCO installer by browsing to:

https://<servername>/downloads/index.html

Alternatively, you can choose to make the MSI available at some other location on your network.

Users must have temporary administrator privileges on their computer to install ZCO.

Once installed, ZCO features an auto-upgrade function that can be used to keep users up to date with the latest version. Auto-upgrade checks whether a more recent version of ZCO is available at the above location when Outlook is started, and if a new version is found, the user is given an opportunity to upgrade to it.

Auto-upgrade can be disabled by customizing the MSI.

You, the administrator, can also obtain the MSI from the Zimbra Utilities Downloads page in the Zimbra Collaboration administration console:

HomeTools and MigrationDownloads

You can obtain only signed versions of the MSI using administration console.

2. Customizing the Installer

There are two parts to configuring ZCO on a user’s computer:

  • Install ZCO

  • Create an Outlook (MAPI) profile

By default, creation of a MAPI profile requires the user to enter, at a minimum, the server name, their account name, and their password.

Users can also specify connection security settings, proxy settings, and download settings. To reduce the burden on the user, you can pre-customize the MSI so that it sets specific options automatically during profile creation.

To customize the installer with your specific configuration details, you run the ZmCustomizeMsi.js file located in the Zimbra download directory on the administration console.

Areas that can be customized include:

  • The default profile name

  • Zimbra Collaboration server name

  • Secure connection options

  • Proxy settings

  • Single Sign-on options (assuming a SPNEGO server configuration)

  • Password rules

  • Free/Busy lookup

  • GAL sync mode

  • GAL sync limiter

  • Disabling auto-upgrade

  • Change the Zimbra branding to your company name or brand using the rebranding tool

  • Enable Report Issue to the system administrator in ZCO

  • Simplified Support View

  • ZCO Database Automatic Compaction

  • Using Middle Name Search

If your environment uses Single Sign-on, it is possible to set things up such that your users don’t need to enter any data to create a profile.

To see a complete list of customization options, copy ZmCustomizeMsi.js to a folder on a Windows computer, open a command prompt in that folder and run:

cscript ZmCustomizeMsi.js
Customizing the MSI causes it to set some additional registry settings in HKEY_LOCAL_MACHINE\Software\Zimbra during MSI installation. These registry settings can also be configured manually, for example, using Group Policy.

Overview of the Customization Process

  • Obtain the unsigned MSIs. It is crucial that ZmCustomizeMsi.js is used to modify the unsigned MSI file. Customizing the Zimbra-signed MSI file is seen as tampering by the Windows SmartScreen, presenting your users with a warning at installation time.

The unsigned MSIs are available at:

/opt/zimbra/jetty-distribution-<version>/webapps/zimbra/downloads

  • Customize the MSIs following the sections following.

  • (Optional) Sign the MSIs with your own company’s signing certificate. (If you don’t do this, Windows SmartScreen warns users at install time that the MSI is unsigned)

  • Place the modified MSIs back on the server. You can either place them in the above directory or use the Zimbra Collaboration administration console to upload them: Home > Tools and Migration > Do Client Upload

  • Generate a new index.html file either by restarting the Zimbra Collaboration server or running /opt/zimbra/libexec/zmupdatedownload.

Adding ZCO Server Credentials

Here is a simple example of how you would customize the MSI to specify the server name, port, and secure connection details. While using the resulting MSI users would only need to add their account name and password when they create a profile.

  1. From the administration console, copy the ZmCustomizeMsi.js file and the ZCO MSI file to a folder on a computer running the Windows platform.

  2. Open the Windows command prompt in that folder.

  3. Type the following command all on one line:

    cscript ZmCustomizeMsi.js <MSI> -sn <servername.com> -sp <port> -ssl <1|0>
    Command Description

    ZmCustomizeMsi.js

    The customization script

    <MSI>

    Path to the unsigned ZCO MSI file to be customized

    -sn

    Zimbra server name (DNS) to be configured

    -sp

    Port number for ZCO connections to use. For non-secure connections, the default is 80. For secure connections, the default is 443. Your configuration can be different.

    -ssl

    Set this to 1 if you want all connections ZCO makes to the server to be secure (SSL), 0 otherwise. See the Zimbra wiki page ZCO Connection Security for more information about connection security.

  4. Press Enter. The ZCO MSI file is modified

  5. To verify that the modification is correct, run the MSI installer and create a dummy profile. The Zimbra Server Configuration Settings dialog should include the server name, server port, and the checkbox marked/unmarked for whether to use a secure connection.

  6. Sign the resulting MSI with your private signing certificate.

You can now make the customized MSI file available to users by placing it back on the server.

Setting the Password Rule

You can control whether or not the account password gets stored in the profile.

Use the -pw switch followed by a 1 or a 0.

  • 0: prevents the account password from being saved in the profile. Users are prompted for the password every time they start Outlook.

  • 1: the account password is encrypted and saved in the profile (default).

Configure Zimbra Free/Busy Provider

Zimbra Connector for Outlook (ZCO) provides a new way to obtain Free/Busy information: the Zimbra Free/Busy Provider. The new provider correctly displays tentative, out-of-office, working elsewhere, and similar other statuses.

To set Zimbra Free/Busy provider as default use the switch --usezimbrafreebusy or -zfb followed by 0 or 1.

  • 0: Use the old Internet Free/busy provider

  • 1: Use the new Zimbra Free/Busy provider

By default the shipped MSI has --usezimbrafreebusy or -zfb set to 0. You need to set it to 1 to activate Zimbra Free/Busy for users.

To rollback to Internet Free/Busy,

  1. you need to set --usezimbrafreebusy or -zfb to 0 and create a new ZCO installer.

  2. Users need to uninstall the current version of ZCO.

  3. Users must then reinstall ZCO with the MSI which has --usezimbrafreebusy or -zfb set to 0.

Modifying the GAL Sync Mode

When you start Outlook against a profile for the first time, ZCO downloads all mail data from the server. It also downloads the Global Address List (GAL). All downloaded data remains in sync with the server data.

Mail data typically needs to be synchronized frequently, but in most organizations, the GAL changes only infrequently. This -gsm switch can be used to control when GAL-syncs occur.

To set the GAL-sync mode, use the -gsm switch followed by 0, 1 or 2.

  • 0: enables automatic and manual GAL-syncs.

See below for a discussion on when automatic GAL-syncs occur

  • 1: disables automatic GAL-syncs.

(GAL-sync only happens when the user chooses Zimbra ribbonSync Global Address ListUpdate Global Address ListUpdate Global Address List

  • 2: disables GAL-sync

Limiting Automatic GAL-Syncs

When the GAL Sync Mode is automatic, ZCO initiates a GAL-sync at the following times:

  • At Outlook startup

  • When the user presses F9

  • At the Outlook Send/Receive interval (Send/Receive ribbon > Send/Receive Groups > Define Send/Receive Groups > Schedule an automatic send/receive every XX minutes - default 30)

  • When the user switches from Offline to Online mode

In all cases, the GAL-sync frequency is limited so that after a successful GAL-sync, subsequent syncs are permitted only after a specified interval. This interval defaults to 4 hours (240 minutes). Modify the value for a single user by changing the Windows Registry key GasSyncMinutesBetween. To customize behavior for an entire organization, configure your custom installer using the -gsl switch.

The number that follows the -gsl switch is the number of minutes that must elapse between successful GAL-syncs. The default value is 0 which is equivalent to 240 minutes. For example, setting this to 480 would prevent GAL-syncs from happening more frequently than every 8 hours.

In release 8.8.12 and earlier, the default behavior was for immediate synchronization. To maintain that behavior, set the limiter value to 1 second using one of the methods mentioned above.

Setting the Location of Local Failure Messages

If ZCO encounters a problem during synchronization, it generates a Local Failure Message. These Local Failure Messages don’t get synchronized to the server. By default, they get created in the Inbox, but you can use the --inbox-failures-off switch to create them in the Sync Issues folder instead.

Configuring Single Sign-On (SSO)

When configuring SSO, users can create a profile without having to enter their username and password. In this case, authentication is done using the username and password that they used to log into Windows.

To use SSO, first configure SPNEGO on the Zimbra Collaboration server. See https://wiki.zimbra.com/wiki/Configuring_SPNEGO_Single_Sign-On.

To make use of this, the user ticks the Connect using my Windows Login Credentials checkbox on the Server Configuration property page when they create their profile. However, by using the --single-signon switch you can relieve them of this burden. The value can be 0, 1, or 2:

0: the Connect using my Windows Login Credentials tickbox is hidden.

This value is for organizations that don’t use SSO.

1: the checkbox shows in the Zimbra property pages, unticked by default.

2: the checkbox is both shown and ticked by default.

The server name used in the ZCO profile must match that in the SPNEGO configuration, therefore it makes sense to incorporate the server name into the MSI before installation of ZCO using the -sn switch.

Example:

cscript ZmCustomizeMsi.js <MSI> -sn <spnegoserver.example.com> -sso 2

For more information, see Appendix B, Configuring SPNEGO Single Sign-On for Zimbra Collaboration in the Zimbra Collaboration Administrator Guide.

Disabling Auto-Upgrade

When a user launches Outlook, by default ZCO checks Zimbra Collaboration for a newer version of ZCO. If a newer version is available, the user receives a prompt with the option to upgrade.

You can disable the auto-upgrade feature using the --disable-autoupgrade switch.

Database Automatic Compaction

Zimbra administrators can now compact large ZCO databases to resolve fragmentation and reduce the size. This process improves performance.

Every time Outlook starts, ZCO checks the databases' condition to determine if the databases need compaction. Below conditions trigger automatic compaction. Each of these conditions is configurable.

Format
cscript ZmCustomizeMsi.js <MSI> <switch> <value>
Time since the last auto compaction

Switch

Value

Description

--autocompactdays, -acd

-1

DBs are never compacted

0

Attempts to compact DBs on each Outlook login

1-300

Number of days after which ZCO attempts to compact the databases

Example
cscript ZmCustomizeMsi.js <MSI> --autocompactdays 15

ZCO attempts to automatically compact the database after 15 days.

Minimum GAL DB size required to initiate autocompaction

Switch

Value

Description

--autocompactdbminsize, -acdbms

10-500 (MB)

The minimum GAL DB size after which ZCO autocompacts it. Enter values only in the specified range.

Example
cscript ZmCustomizeMsi.js <MSI> --autocompactdbminsize 256

ZCO attempts to compact the database if the .db file exceeds 256 MB.

Minimum ZCO DBs' size required to initiate autocompaction

Switch

Value

Description

--autocompactzdbminsize, -aczdbms

200-2048 (MB)

The minimum ZCO DB size after which ZCO autocompacts it. Enter values only in the specified range.

Example
cscript ZmCustomizeMsi.js <MSI> --autocompactzdbminsize 1024

ZCO attempts to compact the database if the .zdb file exceeds 1024 MB.

Display to users, auto compact progress information

Switch

Value

Description

--autocompactshowprogressui, -acspui

0

The user does not see the progress bar regarding the auto compaction.

1

The user sees a progress bar dialog which shows the status of auto compaction

Example
cscript ZmCustomizeMsi.js <MSI> --autocompactshowprogressui 1
ZCO shows a progress bar dialog to users while the compaction is in progress. If you disable the progress dialog, the compaction still proceeds in the background and users may see the Outlook splash screen for a bit longer than usual.

Hiding Email Aliases in the GAL

ZCO stores a copy of the GAL locally and makes it available to Outlook as an Address Book.

By default, accounts which have alternate email addresses (known as aliases) result in multiple entries in the GAL.

If you do not want aliases to appear in the GAL, you can disable this option using the --galsync-disablealiases 1 switch.

When this is disabled, users cannot search for aliases when addressing mail.

Note that a change to this value takes effect on a particular client only after the user resets their GAL. To reset the GAL:

Zimbra Ribbon > Sync Global Address List > Reset Global Address List

Setting the ZCO Display Language

By default, ZCO sets its display language to the Outlook display language.

You can override this with the -lang <LCID> switch, where <LCID> is the decimal LCID value of the language you want to display (1033 for US English, 1041 for Japanese, etc.).

This override is essential if you want to use ZCO’s French Canadian translations for example (since there is no corresponding French Canadian edition of Outlook), in which case the LCID should be 3084.

An individual user can also set the display language via the Language option on ZCO’s Advanced Settings dialog.

Other supported languages include Arabic, Basque, Catalan, Chinese (Simplified PRC, Traditional HK, and Traditional TW), Danish, Dutch, English, French, French Canadian, German, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Lao, Malay, Norwegian, Polish, Portuguese (Brazil and Portugal), Romanian, Russian, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese.

The language used during ZCO installation is based on the current Windows locale.

Rebranding ZCO

You can change the Zimbra branding in ZCO to your company name or brand.

  1. From the administration console, click Downloads link.

  2. Open the Zimbra Connector for Outlook Branding MSI.vbs (Visual Basic) file.

  3. At the start of the script, replace “Foobar” with your company name or value:

Value Description

Brand

Substitutes all occurrences of “Zimbra” in the product, except the Zimbra copyright statement in the ZCO About window. (maximum 30 characters)

Company

Appears only in the .msi file’s summary information (right-click and select Properties) and in the Control Panel entry for the installed program under Publisher. (no character limit)

DefaultProfileName

Provides a name for the default Outlook profile to be created as part of the installation if none already exists. (maximum of 64 characters)

AboutLink

The URL that appears in the Control Panel entry for the installed program under Support Link. (no character limit)

DocumentLink

The Click here for documentation link on the ZCO About dialog. This link normally points to a Zimbra PDF document but can be redirected to your custom web documents. (maximum of 260 characters)

Run the following script on the ZCO .msi file that users use to install ZCO:

cscript ZimbraBrandMsi.vbs ZimbraOlkConnector.msi

If a previous version of ZCO was installed on the target machine, uninstall ZCO before running the newly branded installation.

Your company name or value now replaces the Zimbra brand, and the Zimbra icon gets replaced by a generic icon.

Existing Outlook profiles created using the unbranded package should remain usable but with the old "Zimbra - …​" store name.

Enable the Report Issue feature in ZCO

Admins can enable the Report Issue feature in ZCO by using the --reportissue-adminemailid or -riaeid switch.

Example:

cscript ZmCustomizeMsi.js <MSI> --reportissue-adminemailid <adminEmailId@example.com>

This feature enables ZCO users to report issues to the admin user whose email id appears in the --reportissue-adminemailid switch. The Admin user gets two emails when users report a problem using this feature:

  1. Share notification email for a compressed log archive file placed in the user’s briefcase folder under ZCOLogs folder, shared with admin user.

  2. Issue detail email containing the user’s report about their issue, along with the link to the shared folder path where the relevant compressed log archive file is uploaded.

  • Admins might not be able to access the shared folder if the user manually changed the sharing permission. Manual intervention is then required to regain access to the ZCOLogs shared folder.

  • Admins should delete the compressed log archive files from the ZCOLogs shared folder after their use to avoid exceeding the email quota limit for the users.

Simplified Support View

The Simplified Support View hides some of the Zimbra Support Group buttons on the ZCO UI. By default, all the Zimbra Support Group buttons get displayed on the ZCO UI.

Use the --simplifiedsupportview or -ssview switch followed by 0 or 1:

  • 0: To display all the Zimbra Support Group buttons.

  • 1: To hide the below Zimbra Support Group buttons.

    • Open By Zimbra ID

    • Set Sync Token

    • Zimbra Properties

    • Advanced

    • Logging > Restore default Log settings

    • Logging > Advanced Log settings

Example:

cscript ZmCustomizeMsi.js <MSI> --simplifiedsupportview 1

ZCO has enhanced the address book search feature. The search now includes looking for substrings within the name fields. It is effective specifically when the fields contain multiple words.

For the below example, this feature enables one to search for the word Azam though it is part of the first name:

First Name: Ahmad Azam
Middle Name: N
Last Name: Ul Haq

This feature can be enabled or disabled in the installer using the -imn switch followed by 0 or 1:

  • 0: To disable Middle Name Search.

  • 1: To enable Middle Name Search.

Example:

  • To enable:

    cscript ZmCustomizeMsi.js <MSI> -imn 1
  • To disable:

    cscript ZmCustomizeMsi.js <MSI> -imn 0
Since this feature expands the search space, it might take longer when the GAL size is large (greater than 100,000 entries). In such cases it is advisabble to switch this feature off.
The flag is stored in Windows Registry with the key name IncludeMiddleNameInSearch at the path Computer\HKEY_CURRENT_USER\Software\Zimbra\

3. Installing ZCO

This chapter provides information about what server configuration information a user needs to install ZCO, what takes place when ZCO is installed on individual computers, and what happens during the initial synchronization of ZCO and Outlook.

Installation Prerequisites

If you did not modify the MSI, the user needs the following server configuration information in order to create an Outlook profile. Be sure to provide this information to your user before they install ZCO so they can complete their installation of ZCO:

  • The Zimbra Collaboration server name

  • Whether to select Use Secure Connection (SSL). See below.

  • Their email address

  • Their password

As mentioned in the previous section, they will not need their email address or password is SSO is being used.

Using Secure Connections (SSL)

By default, all connections that ZCO makes to the server will use SSL to verify the server and encrypt the data.

Some server configuration is required for this to function properly:

  • zmtlsctl must be set to HTTPS on the server (this is the default setting for 8.0.7 and later). For more information about zmtlsctl, see the Zimbra Collaboration Administrator Guide.

  • The server must have a valid SSL certificate. See Managing SSL Certificates for Zimbra Collaboration in the Zimbra Collaboration Administrator Guide.

  • Default Zimbra Collaboration installations generate their own self-signed certificate. This can be used, although in order for ZCO to trust it, the root CA certificate that signed it must be placed in the Trusted Root Certificate Authorities section of the Windows Certificate store on all user machines. This can be done as described in the Zimbra Wiki page ZCO Connection Security.

Failure to place the root CA certificate in the “Trusted Root Certificate Authorities” will result in ZCO displaying a warning that the certificate could not be verified.

Authentication

When Outlook is started, ZCO authenticates against the server account specified in the profile. ZCO supports 4 kinds of authentication

  • UserName + Password

  • Single Sign-on

  • Two-step Authentication

  • Certificate Authentication

UserName and Password

See earlier in this guide.

Using Single Sign-on

See earlier in this guide.

Using Two-step Authentication (2FA)

Two-step authentication can be enabled for an individual user account via the Two Factor Authentication section in the Zimbra Admin Console’s Advanced settings.

The user will then need an authentication app (e.g. www.authy.com) installed on the user’s computer or smartphone which can be used to generate time-limited passcodes. The user is prompted to enter a passcode in Outlook whenever ZCO signs onto the Zimbra server.

Initial setup of the authentication app for an individual user should be performed using the Zimbra Web Client (after which, passcodes from the app are equally usable with either ZCO or ZWC):

  1. Sign onto ZWC using the user’s normal credentials.

  2. Under ZWC’s Preferences tab select Accounts.

  3. From the Primary Account Settings, select Set up two-step authentication…​.

  4. Follow the setup wizard instructions, supplying a passcode from the authentication app when prompted.

Using Certificate Authentication (CertAuth)

Client certificate authentication requires a suitable individual client certificate to be installed in the Personal section of the end user’s Windows Certificate Store on the computer running Outlook. The certificate generation process itself is the same as that required for ZWC - see the Zimbra Wiki page Client Cert Auth using X.509 for more details.

When configuring a ZCO profile for certificate authentication the port number which has been set in zimbraMailSSLClientCertPort. Currently, this needs to be specified alongside the server name. Hence it makes sense to customize the ZCO installation MSI to incorporate this port number and the corresponding server name before deploying the ZCO MSI.

Installation

It only takes a few minutes for users to install ZCO on their computers and configure the connection to Zimbra Collaboration. You must provide the user with temporary administrative privileges and the server configuration information.

Installing ZCO on a computer which has no existing MAPI profiles results in the creation of a new profile called Zimbra (or other, if this was set using ZmCustomizeMsi.js’s --profile-name option).

Installation does not remove any previous Outlook profiles or accounts. The user can view previous profiles by navigating to Start > Settings > Control Panel > Mail > Show Profiles.

Mail profiles can combine a Zimbra account with an IMAP, Exchange, or POP account, but there can be at most one Zimbra account in a profile.

To add a new profile, users select Add on the Show Profiles dialog and follow the prompts.

For more information about the ZCO installation process, see the Zimbra Connector for Microsoft Outlook User Guide.

Upgrade

In general, when a new version of ZCO is installed over an existing ZCO installation, the profile will be automatically upgraded.

Synchronizing ZCO with Outlook

The first time a user opens Outlook after ZCO is installed, the user’s Outlook mailbox must synchronize with Zimbra Collaboration. If users have been using the Zimbra Web Client and have email messages, folders, tags, signatures, contacts, personal calendars, appointment reminders, and tasks on Zimbra Collaboration, this information is synchronized with their Zimbra profile in Outlook.

The initial synchronization can take a few minutes or longer, depending on the size of the mailbox and the network speed. With slow networks and/or large mailboxes, the initial synchronization can take several hours. It is advantageous to install ZCO while using a fast and reliable wired company network. It is also strongly advised that Antivirus is disabled during the initial sync, otherwise the Antivirus software can prolong the initialization by virus checking messages as they are placed in the ZDB.

If users use the default Zimbra profile, their synchronized data is saved in the zimbra.zdb file located in the user’s AppData\Local\Microsoft\Outlook folder.

When Zimbra Collaboration is restored from a Zimbra backup, ZCO profiles might have to be recreated.

Synchronization Frequency

ZCO synchronizes automatically at the following times:

  • At Outlook startup

  • At the frequency specified in Outlook’s Send/Receive Groups dialog box (default is 30 minutes)

  • When a change is detected on the server or in Outlook

  • When the user presses F9

  • Immediately after switching from Offline to Online

Resyncing the GAL for Contact Group Support

To obtain full support for contact groups for profiles that were created with older versions of ZCO, it is necessary to perform a full GAL reset on your ZCO client to ensure contact groups and their members are synced correctly with Zimbra Collaboration.

Zimbra Ribbon > Sync Global Address List > Reset Global Address List

For more information about ZCO synchronization, see the Zimbra Connector for Microsoft Outlook User Guide.

Stale profile handling

If users don’t access their ZCO Profile for long durations (e.g. more than 3 months), then the profile becomes stale. In such a scenario, when user launches Outlook, then a pop-up message "Your mailbox is too far out of date to be synchronized with the [ZIMBRA] server. Do you want to download fresh mailbox data the next time you start Outlook?" is displayed with YES/NO buttons.

If user clicks “YES” button, it will delete stale profile data files (zdb, .db etc) and on next Outlook launch ZCO will fetch all fresh data from the server. (Just like configuring the new profile)

If users clicks "NO" button, then same error message will be shown on next ZCO profile launch.

4. Zimbra Features in Outlook

The following table shows how Zimbra Web Client features map to the same in ZCO. See the Zimbra Connector for Outlook User Guide (available from the ZCO About dialog) for more information.

Feature Location in Outlook

Zimbra Personas

Zimbra Ribbon > Personas

Zimbra Mail Filters

Zimbra Ribbon > Zimbra Server Rules

Out-of-Office Reply

Zimbra Ribbon > Zimbra Out of Office Assistant

Zimbra Mailbox Quota

Zimbra Ribbon > Mailbox Quota

Enable/disable automatic GAL-Sync and manually force GAL-Sync

Zimbra> Sync Global Address List

Select/Deselect Error Messages

Zimbra Ribbon > Error Reports > Save in Inbox

Sharing

Users can share Zimbra mail folders, calendars, contacts, and tasks and access those shared by another Zimbra user

Zimbra Tags

Synchronized with Outlook Categories.

Personal Email Certificates (S/MIME)

ZCO supports sending/receiving of signed and encrypted messages using S/MIME. The public keys required for these operations can be stored both in the GAL and in Personal Contacts.

Those is the GAL are propagated to the Global Address List stored on user’s computer during GAL Sync. They are readonly.

Those in Personal Contacts are synchronized bi-directionally with Zimbra Collaboration.

Advanced Settings

Users can modify the following advanced settings from the Advanced button, available from:

Zimbra Ribbon > Advanced
Note: Any changes made in the Advanced Settings dialog are stored in the registry and affect all profiles.
Feature Description

Connection Timeouts

Configure ZCO connection settings. The default settings for send, receive and option/receive are 900000 milliseconds, or 15 minutes

GAL Sync Optimizations

Set GAL sync time, including sleep time, and sleep after. If the user’s system is slow due to GAL-sync, they can configure their system to go to sleep after a specified number of contacts have been synced.

LDAP

The LDAP default is disable. Users can enable LDAP and enter the server name.

Delegate Calendar Sync

Select to sync all calendar content, or select to sync partial calendar content by selecting a specified number of days to sync.

Enable local rules

Check this box to allow users to enable local Outlook rules. By default, local Outlook rules are disabled.

Store password in the profile

Check this box for users to store their passwords in their profiles. Uncheck this box if you do not want user passwords stored in their profile. They enter their password at each login.

Synchronize Signatures

Check this box to sync email signatures from Outlook’s Signatures and Stationary dialog with the server.

Synchronize Preferences

Check this box to sync preferences, such as Read Receipt options in Outlook’s Options dialog.

Synchronize on Change

Synchronizations are typically carried out at the interval specified in Outlook Send/Receive Groups dialog. But if this option is selected, ZCO bypasses the interval and syncs within 60 seconds if it detects a change made by Outlook or a change made by the server. (Changes other users make in folders that they have shared with you are synced at the interval specified in Outlook Send/Receive)

Automatically mount shared stores

If a link to a shared folder is accepted in Zimbra Web Client, then when this option is enabled, the shared store is automatically added to Outlook.

Language

See Setting the ZCO Display Language.

Free/Busy Lookup in ZCO

If the Zimbra Collaboration server CA certificate is self-signed, free/busy lookup in Outlook fails with the error

An error occurred reading Internet free/busy data. General failure.

To fix this issue, add the CA certificate to Internet Explorer’s Trusted Root Certification Authorities.

Outlook AutoArchive

Outlook’s AutoArchive function does not remove files from the server. It will only add the files to the PST archive.

To better manage storage on Outlook, the AutoArchive feature is now available for ZCO users. The feature controls the Outlook Inbox and folders and helps manage the storage by shifting older items to an archive you want to maintain.

For more information on ZCO’s AutoArchive feature and how to enable it, please refer to the Auto Archive section in the user guide.

Forwarding Invitations

If you forward a meeting invitation to another user, a notification is sent to the original meeting organizer because you have now extended their invitation to a new invitee.

5. Troubleshooting ZCO

Troubleshooting Aids

ZCO includes several troubleshooting aids:

  • Failure Notices: If ZCO is has difficulty synchronizing a particular item it places a Failure Notice message in the Outlook’s Inbox or Sync Issues folder.

  • The Zimbra ribbon’s Support group

  • ZCO Logging: ZCO can be configured to write detailed logs of an Outlook session.

  • Core Dumps: In the event of a crash, ZCO automatically generates a core dump which can be analyzed by the support team.

Installation Problems

Occasionally, conflicts can occur during installation, so if this is a new installation that has never functioned correctly, consider uninstalling ZCO, rebooting and reinstalling.

Local Failure Messages

When ZCO is installed, a Sync Issues folder with subfolders is created in the user’s Outlook Folder List. If errors are found when Outlook syncs with the server, a sync failure notification is sent to both the user’s Inbox and the Sync Issues folder. These messages are created to help Zimbra technical support and engineering debug and fix errors.

To view the Sync Issues folder, click the Folder List icon in the Outlook Navigation Pane. The Sync Issues folder is displayed in the Folder List. Users can tell when new messages are in these folders when the folder is bold and the number of unread messages is displayed.

To prevent Local Failure Messages being placed in the Inbox, deselect:

Zimbra Ribbon > Error reports > Save In Inbox

Review the Failure messages. The problem might be simple to resolve, such as an out of quota message. If you cannot resolve the error based on the message, submit the messages with a support case to Zimbra Support.

Support Group on the Zimbra Ribbon

When ZCO is installed, the Zimbra Ribbon is created, and this contains a group called Support. If users are having issues with specific emails or folders, you can use this group to collect information to help debug the issue.

The Zimbra Support group buttons are explained below.

Show Original

Items are propagated from the Server to ZCO in MIME format where they are converted to MAPI format. When conversion problems occur, it can sometimes be useful to see the original MIME. For this, select the message and click Show Original.

The Show Original button shows the MIME of the original item in the default Internet browser.

If the user has not logged into their account using ZWC, the browser will prompt for the account login information before you can view the item

The MIME includes the Zimbra Item ID, Folder ID, and any other information contained in the original item (such as tags, flags, header information, etc.).

Opening an Item by ZimbraID

All items on the server and in ZCO have a unique ID called the ZimbraId.

The Open By Zimbra Id button allows you to view an email, appointment, task or other item in Outlook by its Zimbra Id. You can find the ZimbraId of an item by using the Show Original button in the Zimbra Support Toolbar, or by the number listed in a Local Failure Notice.

Meeting requests cannot be opened by Zimbra Id. Drafts can be opened, but sometimes generate errors when opened by Zimbra Id.

Set Sync Token (Resyncing Items)

Synchronization between the server and ZCO is controlled by a Sync Token.

Sync tokens increase in numerical value between one sync and the next. Setting a sync token to an earlier number allows you to resync any items that failed to sync between the sync token you set and the current sync token.

The Set Sync Token button allows you to set the Zimbra sync token.

Enter the sync token to set. Click OK. To attempt to resync the item, click Send/Receive.

Note: In some cases, sync failures might not be resolved unless the Sync Token number is set back several tokens before the failed sync.

View Zimbra Properties

The Zimbra Properties button shows key Zimbra-related MAPI properties of an item. A support engineer may request that you use this feature. You can click Save to File to save the MAPI properties of an item to a file.

ZCO Logging

ZCO includes a comprehensive logging tool called the ZCO Log Control (zcologctl.exe). You can open this in two ways:

  • From within Outlook: Logging > Advanced Log Settings

  • From Windows: Start > Run > zcologctl.exe <enter>

The Advanced button hides some detailed options which should not be modified unless your support engineer advises you otherwise.

Note that ZCO always generates a small summary log (with a filename ending in SUMMARY.log) every time Outlook runs. This file is generated even when logging is disabled, and contains a top-level summary of folders and messages that have been opened, synchronizations that have been done, and any significant errors or warnings.

To enable more detailed logging do one of the following:

  • Select the Logging button on the Zimbra Ribbon and select Enabled.

  • Open ZCOLOGCTL.EXE and select Enable Logging.

Outlook will run more slowly when logging is enabled so be sure to disable it when not troubleshooting

All logs are written to a folder called ZCOLogs in the path specified in the ZCO Log Control. You can open the logs folder via Zimbra Ribbon > Logging > Open Log Folder.

Some general tips for capturing effective troubleshooting information for Zimbra Support include:

  1. Disable Windows Search to avoid capturing unnecessary logging

    start > run > services > Windows Search > Properties > Stop + _Disabled_
  2. Disable foreign add-ins

  3. Empty ZCOLogs directory by selecting the Zimbra Ribbon > Logging > Clear Logs to ensure that only logs which span the reproduction of the problem remain in ZCOLogs

  4. Start Outlook and reproduce the issue

  5. Take detailed notes of the steps: times, ZimbraIDs, subjects, etc.

  6. Take screen shots, or a screen video if possible

  7. Select Zimbra Ribbon > Logging > Create Log Archive to create the compressed log archive. This compressed log archive contains all the files present in ZCOLogs folder (other than zip files and files in subfolders) and can be used while reporting an issue.

Log files are generally intended for support engineers, but you might be able to diagnose simple problems (such as lack of server connection) yourself by opening the log file and searching for ERROR or WARNING.

Outlook Crashes

If Outlook closes unexpectedly (for example, with the warning Outlook…​needs to close), look in the ZCOLogs directory for core dumps indicated as *.DMP files and provide these to Zimbra Support.

Outlook Hangs

If Outlook hangs, Zimbra Support might ask you for a hang-dump. The easiest way to generate a hang-dump is to right click on OUTLOOK.EXE on Task Manager’s Processes tab and choose Create Dump File.

The Zimbra Calendar will not Sync

  1. Verify that the user’s account has synced.

  2. Check Local/Server Failure messages in the Sync Issues folders.

  3. Submit a case with the logging information to Zimbra Support.

Unable to Access a Shared Item

  1. Verify that the user has accessed the calendar correctly:

    1. Open > File > Other User’s Mailbox. The Global Address Book is displayed.

    2. Select the sharing user from the list. The shared item should sync automatically.

  2. Submit a case with the logging information to Zimbra Support.

The .zdb File is Corrupt

A user receives a Local Failure message stating that the .zdb file is corrupt. To fix this issue, you must repair the .zdb file. The .zdb file includes all Outlook data from Zimbra Collaboration in .pst format: messages, contacts, appointments, tasks, etc.

Use the scanpst.exe tool to repair any .zdb file that Outlook/ZCO has trouble opening.

Conflict with Antivirus Software or other Outlook Add-ins

It is not uncommon for ZCO to encounter problems when running third-party Outlook add-ins or antivirus software. Try disabling the add-ins before retrying to use ZCO. To report the problem, log a bug with Zimbra, list all of the Outlook add-ins that are installed, and indicate the add-ins you think are causing the conflict.

Repairing ZCO

  1. Locate the ZCO MSI used to install ZCO and download the file to your computer.

To find out which version of ZCO is installed, open Outlook and go to: Zimbra Ribbon > About Zimbra.
  1. Click the file to open. When the MSI is run when ZCO is already installed, it opens with the options to repair the connector.

  2. Click repair. ZCO is reinstalled.

Uninstalling ZCO

To remove ZCO, including all components except the Zimbra profiles, on your computer use the Windows control panel’s Add or Remove Programs section.

Resolving Mailbox Sync Problems

If a user’s mailbox cannot receive new mail, becomes out-of-sync, or the .zdb file becomes corrupted, it may be useful to create another profile to see if the problem persists.

In some cases, it might be necessary to uninstall ZCO, delete the profile and .zdb, and start over.

Resyncing the GAL for Contact Group Support

For contact group support, perform a full GAL reset on your ZCO client to ensure contact groups and their members are synced correctly with ZCS.

Zimbra Ribbon > Sync Global Address List > Reset Global Address List

Outlook search is slow or not working

When you start ZCO with a Click-to-Run version of Outlook, you might see a message box asking for permission to change the registry settings. This will happen if recent Microsoft Office updates have removed the ZCO created registry keys, which is required for Outlook search to work properly. Allow ZCO to reset the registry settings. If denied, outlook search might not work properly.

How to determine whether you have a Click-to-Run version:

  1. In your Microsoft Outlook 2013 or later application select File, then Office Account then select About Outlook.

  2. On the right side of the screen, locate About Microsoft.

  3. If the installed release of the Office product is a Click-to-Run edition, the text will include "Click-to-Run".

In some cases, it might be necessary to recreate the profile for Outlook search to work properly.

Contacting Zimbra Support

You can contact Zimbra Support at support@zimbra.com. To provide the highest level of service, gather the following information before contacting support.

  • Detailed description of the problem.

  • Steps for reproducing the problem.

  • Logs that span the problem.

  • Crash Dumps. These are generated automatically if Outlook crashes. For ZCO 8.5.0 and later, crash dump logs are generated in ZCOLogs.

  • Hang Dumps

Beyond the above information, include the following information if it is relevant to your problem.

  • Install logs: If users are experiencing issues with installing ZCO, include the install logs. You can create install logs by running the following command.

    msiexec /i <zco-installer.msi> /lv <zco-install.log>
  • For example, the following command creates a ZCO install log named case00012345-zco-install.log.

    msiexec /i  ZimbraConnectorOLK_8.8.8.1742_x86.msi /lv case00012345-zco-install.log
  • Sync error messages: If users are experiencing issues with syncing, include any relevant error messages. You can find sync error messages in the Local Failures and Server Failures folders, located in the Sync Issues mail folder. For more information about the Sync Issues folder, see earlier in this guide.

Additional Resources

If your issue is not a known or common issue, or is persisting despite troubleshooting, you can use the following additional resources to search for information about your issue or contact Zimbra Support for help.

  • Zimbra Forums: The Zimbra Forums, http://community.zimbra.com, are a great place to find answers to problems and issues you may be experiencing.

  • Zimbra Wiki: The Zimbra Wiki has many articles and reference material about ZCO. Go to http://wiki.zimbra.com/wiki/Category:ZCO.

  • Web Search: If you cannot find a solution to your issue through the Zimbra Forums, you might be able to find other resources or information using a Web search.