Zimbra Connector for Microsoft Outlook: Administration Guide

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.

ZCO is supported on the following Microsoft Operating Systems:

ZCO is supported on the following versions of Microsoft Outlook:

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

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

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

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

New users typically obtain the ZCO installer by browsing to:

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

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:

The unsigned MSIs are available at:

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

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.

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

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.

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.

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,

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.

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

(GAL-sync only happens when the user chooses Zimbra ribbon → Sync Global Address List → Update Global Address List → Update Global Address List

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

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.

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.

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 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.

Example:

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

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.

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.

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:

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.

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

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

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.

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

Example:

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:

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:

Example:

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:

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

Example:

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:

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:

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

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.

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

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.

ZCO synchronizes automatically at the following times:

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.

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

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.

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.

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

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

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

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.

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.

ZCO includes several troubleshooting aids:

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

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:

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.

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.

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.

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.

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.

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.

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

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.

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.

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:

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

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

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.