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:

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.

This controls whether or not the account password is stored in the profile.

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

When you start Outlook against a profile for the first time, ZCO downloads all mail data from server. It also downloads the Global Address List (GAL). Both are subsequently kept 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 are done.

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

When the GAL Sync Mode is set to automatic, ZCO will attempt a GAL-sync at the following times:

In large organizations, with thousands of users, where the server-side GAL changes infrequently, it is recommended that you reduce the GAL sync frequency using the -gsl switch to avoid unnecessary server load.

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

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

When SSO is configured, users can create a profile without having to enter their username and password. Rather, 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. But by using the --single-signon switch you can relieve them of this burden. The value can be 0, 1 or 2:

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 is prompted with the option to upgrade.

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

As mentioned above, ZCO stores a copy of the GAL in the ZDB and makes it available to Outlook as an Address Book.

By default, accounts which have an alternate email addresses (known as an aliases) will 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 will not take effect on a particular client until 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 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 own company name or brand.

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

If ZCO has been previously 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 is replaced with 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 is provided in the above mentioned switch. Admin user will get two emails when users report a problem using this feature:

This display or hides some of the Zimbra Support Group buttons on the ZCO UI. By default all the Zimbra Support Group buttons would be displayed on the ZCO UI.

Use the --simplifiedsupportview or -ssview 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.

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.

The Outlook AutoArchive function is disabled for Zimbra profiles and folders. This feature should not be enabled. Auto-archiving removes files from the server, including items shared with others. This can cause data loss or problems with recurring appointments, shared items, and historical calendar data.

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.