Zimbra Connector for Outlook 5.0.20 (Rev November 2009)
Table of Contents Previous Next


Zimbra Connector for Outlook Administrator Guide

Zimbra Connector for Outlook Administrator Guide
With the Zimbra™ Collaboration Suite Connector for Outlook (ZCO), users can use Microsoft® Outlook® 2003 and 2007 to access the Zimbra Collaboration Suite server and synchronize data with Outlook for offline use. ZCO is a MAPI service provider that is installed on users’ computers.
Important: Client computers must have Microsoft Office Outlook 2003 SP1 or later installed. See Microsoft’s support article http://support.microsoft.com/?id=823633.
Email messages, chat archives, folders, tags, contacts, personal distribution lists, personal calendars, appointment reminders, and tasks are synchronized with the Outlook 2003/2007 client. Zimbra Collaboration Suite server-side configuration for accounts is enforced for Outlook users.
Important: ZCO 5.0 or later will only work with Zimbra Collaboration Suite 5.0 or later servers.
Downloading the ZCO Installation Program
The ZCO .msi file and user instructions can be downloaded from the ZCS Administration Console’s Downloads page. The install program for ZCO is in the Windows Installer .msi format so that it can be easily deployed to individual computers using your group policy software deployment process. Alternatively, you can copy the .msi file to a directory that users can access, and instruct your users to download the file directly.
The ZCO Installation Program
When ZCO is installed, the server name and whether to use a secure connection must be set for every user. Users enter this information when they configure their account.
Optionally, administrators can customize the ZCO .msi file, adding the server and connection information to the install script. If the .msi file is customized, end users only need to enter their email address and password.
Optional step to modify the ZCO .msi file
To modify the .msi file, Zimbra created a Java Script file that runs under the Windows Scripting Host. This file, called ZmCustomizeMSI.js, can be found in the Zimbra download directory on the Administration Console.
1.
Copy the ZmCustomizeMSI.js file and the ZCO .msi file to a computer running the Windows platform.
Note: The ZCO .msi file name is different from the example shown here. Please note the exact file name when you download it.
2.
Open the Windows Command Prompt and go to the directory where the ZmCustomizeMSI.js file is saved. For example, if it is saved in the temp folder on your C drive, you would type cd c:\temp.
3.
cscript ZmCustomizeMSI.js <path/msi-filename> -sn <servername.com>-sp <port> -ssl <1 | 0>//nologo
Press Enter and the ZCO .msi file is modified.
The cscript command includes the following:
ZmCustomizeMSI.js. Name of the .js file
path/msi-filename. Directory path and the ZCO .msi file name. Verify exact name of file.
servername. Zimbra server domain name (DNS) to be configured in the .msi file.
port. Port number to be configured. For non-secured connections, the default is 80. For secured connection, the default is 443. Your configuration can be different.
Note: If your port number is different than the default port for your connection type, your users will need to include the port number when they provide the server name. The server should be entered in the form of example.domain.com:<port>
Whether User Secure Connection should be checked. Enter 1 for the secure connection using a HTTPS connection or enter 0 to use a HTTP connection. (1 | 0)
Example:
cscript ZmCustomizeMSI.js ZimbraOlkConnector.msi -sn server.example.com -sp 443 -ssl 1 //nologo
4.
To verify that the modification is correct, you can run the .msi installer and create a dummy profile. The Zimbra Server Configuration Settings dialog should include the server name, server port, and the check box marked/unmarked.
 
 
Once you have checked the modified .msi file, you can deploy it to users using your group policy software, or you can save it to a directory that users can access to download the file to their computers. Users must have administrator privileges on their computer to install ZCO.
Other Items to Customize in the .msi file
You can make additional changes to the .msi file before users install ZCO to change the following functionality in ZCO:
n
Password Required. Set the password rule to require users to log in every time they retrieve their email. 1 means that the encrypted password is saved in their profile. (default). Users do not need to enter their password when they open ZCO. 0 means that the password is not saved. Users are prompted to enter their passwords whenever they sync to the server.
r
n
GAL sync mode. 2 to disable GAL sync. 1 to make GAL sync a manual option only. 0 for GAL syncs to occur automatically every x days. The interval is controlled by the -gsr switch below. The default is every 7 days. Note that with this option, users can also sync the GAL manually.
r
n
Set the interval for the automatic sync to GAL.The sync consists of a full sync and interval syncs.
r
r
n
Where sync failure notifications are saved. 1 to create sync failure messages only in the sync Issues folders. 0 to create the sync failure messages in the sync issues folders and in the user’s Inbox.
r
Installing the ZCS Connector for Outlook
Installing ZCO creates an Outlook mail profile named Zimbra and designates this profile as the default. This does not remove any previous profiles/accounts. Previous profiles can be viewed by navigating to Start>ControlPanel>Mail>Show Profiles.
Steps to Install the ZCS Connector for Outlook
It only takes a few minutes for users to install ZCO on their computers and configure the connection to the Zimbra server. The user’s Zimbra account must be created, but no specific changes are required on the Zimbra server. Installing ZCO creates a mail profile named Zimbra and designates it as the default profile in Outlook.
If you did not modify the .msi file (as described in “Optional step to modify the ZCO .msi file” ), users will need to know the following in order to complete the installation:
n
Note: If your port number is not 80 or 443, your users will need to include the port number when they provide the server name. The server should be entered in the form of example.domain.com:<port>
n
Whether to check Use Secure Connection (SSL). This box is checked to establish a secure connection to that port.
n
The following describes the installation and configuration steps that are performed on each computer. User instructions can be downloaded from the Administration Console’s Download page. Save the user instructions to a directory that users can access before they install ZCO.
1.
When the MSI installer starts, a Welcome dialog displays, followed by the End-user License Agreement. Users read the license agreement and click I accept the terms in the License Agreement to continue.
2.
When the Confirm Installation page displays, click Next to begin the installation. The dialog displays the progress bar. When the installation is complete, the Installation Complete dialog displays.
3.
Users open Outlook, and if you did not modify the .msi file, complete the Zimbra Server Configuration Settings dialog as follows.
Server Name. This is the Zimbra server domain name (DNS).
Use Secure Connection. Check this box to establish a secure connection to that port.
Email address. This is their Zimbra account email address. The address should be entered as name@domain.com.
Password. This is their Zimbra account password.
4.
They click OK and the installation and configuration of ZCO is complete. The Zimbra profile is created.
Users can now log on and use Outlook.
Final Steps—Initial Sync
The first time users open Outlook after ZCO is installed, their Outlook mailbox must synchronize with the Zimbra server. If users have been using the Zimbra Web Client and have email messages, chat archives, folders, tags, contacts, personal distribution lists, personal calendars, appointment reminders, and/or tasks on the Zimbra server, this information is synchronized with their Zimbra profile in Outlook. The initial synchronization can last a few minutes or longer, depending on the size of the mailbox being synchronized.
If users create the default Zimbra profile, their synchronized data is saved in the zimbra.zdb file located in the user’s Local Settings\Application Data\Microsoft\Outlook folder.
If users used Notes and Journal in Outlook, these items will be lost when an initial sync is performed. In order to keep their Notes and Journal entries, users should save these Outlook items in .pst format before syncing and then import the .pst file after the initial sync is performed.
Note: If you are running McAfee® Security On-Delivery E-mail Scanner feature, the initial sync is very slow. We recommend that this option be turned off for the initial sync with the Zimbra server.
Users can click Tools>Send/Receive>Send/Receive All (shortcut key F9) to update Outlook and the Zimbra server with changes made since the last sync.
Important: When the Zimbra server is restored from a Zimbra backup session, users must perform an initial sync with the Outlook client when they log on.
ZDB Configuration Options
ZCO supports relocating a ZDB file, also known as a roaming profile, as well as ZDB file compaction. You must be logged in on the user’s account to configure their ZDB settings. Further instructions for configuring a user’s ZDB settings are in the How to Install and Use Zimbra Connector for Outlook user guide.
Repairing ZCS Connector for Outlook
You can use the same version of the ZCO .msi file to repair the ZCO software on individual computers.
Note: To find out what version of ZCO is installed, open Outlook and go to Help>About Zimbra Connector for Outlook.
When the .msi file is opened after ZCO is installed, it automatically opens with the options to repair the connector or to remove the software.
n
Repair. This will reinstall the software.
n
Remove the Outlook Connector. This will remove all components, except for the Zimbra Profiles.
Note: The user should not delete the existing Zimbra Profile.
Resolving Mailbox Sync Problems
In the event that a user’s mailbox cannot receive new mail, becomes out-of-sync, or the .zdb file becomes corrupted, you can:
n
Set the Sync Token to an earlier Sync Token number, and attempt to resync the user’s mailbox. For more information on setting the Sync Token, see Set Sync Token on page 12.
n
Choose to force an initial sync of the user’s mailbox. To do this, have the user create another profile, open Outlook, and click Tools>Send/Receive>Send/Receive All to sync with the Zimbra server.
n
Have the user delete the existing .zdb file and then click Tools>Send/Receive. This deletes all data on the user’s computer and recreates the mailbox from the data that is on the Zimbra server, but keeps the same profile.
In some cases, it may be necessary to uninstall the .msi file, delete the profile and .zdb file and start over.
Important: When the Zimbra server is restored from a Zimbra backup session, users should resync Outlook with the Zimbra server.
Zimbra Feature Differences for Outlook Users
Zimbra Collaboration Suite offers account configuration by Class of Service and by account. When the client uses Outlook, many of the features and options configured for the Zimbra account are not enforced in Outlook. Only restrictions that are controlled by the server are enforced.
Users can configure their own Outlook preferences. These are not synchronized with the Zimbra server.
When you view an account’s mailbox from the administration console, the view is from the Zimbra Web Client and may not contain files in Outlook that have not been synchronized.
Note: When items are archived in Outlook (Outlook auto archive or manually), the items are removed from the Zimbra server.
COS and global settings enforced for ZCO users
Zimbra COS features and Global Settings that are enforced include the following:
n
Account quotas. Users can see their account quotas by going to Tools>Mailbox Quota. If they are close to their quota, users can use Outlook Archiving to save files to their computer to prevent going over their quota limit. Archiving removes the messages from the Zimbra server.
n
n
n
n
n
n
n
n
n
n
If the Maximum size of an uploaded file (KB) field is set to 0 in the ZCS Global Settings>MTA tab, messages sent through Outlook cannot be delivered.
Zimbra features in Outlook
Several Zimbra features are available in Outlook. Below is a list of these features and where they are implemented in Outlook.
n
n
n
n
Out-of-Office Reply can be created from Tools>Out of Office Assistant.
Zimbra Web Client (ZWC) only features
The following Zimbra features do not work in Outlook.
n
n
Troubleshooting Options
If the Outlook client is not synchronizing with the Zimbra server or if Outlook is not working correctly, several options are available to troubleshoot the problem:
n
n
If the initial sync did not work, run the .msi file again and select Repair to see if reinstalling ZCO resolves the problem.
n
If Outlook closes unexpectedly (e.g. with the warning “Outlook...needs to close”), generate core dumps for Outlook. Go to the Zimbra Wiki CoreDump page (located at http://wiki.zimbra.com/index.php?title=CoreDump) for directions. The core dump shows what Outlook was doing at the time of the crash. This file should be sent to Zimbra support, at support@zimbra.com.
n
If Outlook is hanging, or behaving strangely, run the Logging Control tool that is installed when ZCO was installed. See “Using Logging Control for troubleshooting” . Send this file to Zimbra support, at support@zimbra.com.
n
Reviewing Sync Issues folders
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 Zimbra server, a sync failure notification is sent to both the user’s Inbox and the Sync Issues folder. To turn off local failure notifications to the user’s Inbox, deselect Errors to Inbox under the View menu.
To view the Sync Issues folder, click the Folder List icon in the Navigation Pane. The Sync Issues folder is displayed in the Folder List. Users can tell when new messages are in these folders if the folder is bold and the number of unread messages is displayed.
If users are having problems using Outlook and continuously receiving errors, the messages in these folders should be submitted with a support case to Zimbra Support. These messages are created to help Zimbra technical support and engineering debug and fix errors.
Using Logging Control for troubleshooting
ZCOLogCtl.exe is installed when ZCO is installed. If users encounter problems when accessing their Zimbra accounts using ZCO, you can enable the logging control tool to log errors and events that occur while they are using ZCB. Logging Control should be used for all troubleshooting. Once you have enabled logging and have recreated the issue, you can then send this log to Zimbra for analysis.
This logging control tool is in the local ID directory, \Program files\Common Files\System\MSMAPI\<LCID> where LCID refers to the local ID of the user. For USA English, this ID is 1033.
The following options can be specified:
n
HTTP Logging. Enabling HTTP logging will log any HTTP traffic.
n
Verbose Logging. Enabling verbose logging will create more detailed logs, but may affect performance.
n
Keep Logging. When you enable this option, the logging control tool saves more than one backup log file. By default, only one backup log file is saved.
n
Log File Path. In this field, you can specify in what directory log files should be saved.
n
Log File Prefix. In this field, you can specify the prefix for log files.
n
Maximum Log File Size. You can indicate the maximum size of a log file. The default log file size is 10 megabytes. When the size of the log reaches the limit, the current log is set aside and a second log is created. If the log file size is set to 0, the size of the log file is unlimited.
When the problem has been recreated, submit a support case and include these logs.
Note: Enable Logging should be unchecked to disable logging when not being used for troubleshooting. If logging is on continuously, performance may be affected.
Zimbra Support Toolbar
When ZCO is installed, the Zimbra Support Toolbar is added to the Outlook Views menu. If a user is having issues with specific emails or folders, you can use this toolbar to collect information to help debug the issue.
To access the Zimbra Support Toolbar, go to View>Toolbars>Zimbra Support. You can also access this toolbar by right-clicking the toolbar area and selecting Zimbra Support from the Toolbar menu. The Zimbra Support Toolbar will be added to the Toolbar View.
The four Zimbra Support Toolbar buttons are explained below.
Properties
The Show Properties button shows a subset of the MAPI properties of an item. You can view MAPI properties of a message and of the folder the message is in by selecting either Message or Folder in the lower left of the MAPI properties dialog. You can save the MAPI properties of an item to a file by clicking Save to File.
Show Original
The Show Original button opens the source of the original item in the default Internet browser. The browser will prompt you for the account login information before you can view the item. The source text includes the Zimbra Item ID, Folder ID, and any other information contained in the original item (such as tags, flags, header information, etc.).
Open By Zimbra Id
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 also find the Zimbra Id of an item by using the Show Original button in the Zimbra Support Toolbar, or by the number listed in a Local Failure Notice.
Note: Meeting requests cannot be opened by Zimbra Id. Drafts can be opened, but will sometimes generate errors when opened by Zimbra Id.
Set Sync Token
The Set Sync Token button allows you to set the Zimbra Sync Token. Sync Tokens track the syncs between an Outlook client and the Zimbra Server. 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.
For example, if an appointment fails to sync to a user’s Outlook client they will receive a Local Failure Notice in their Inbox and Sync Issues>Local Failures folders.
In this example, an appointment failed to sync. To resync this item and update the user’s Outlook client with the most information, the Sync Token must be set to before the request that failed. In this example, the Sync Token must be set to any token before or equal to 55080.
Note: In some cases, sync failures might not be resolved unless the Sync Token number is set back several tokens before the failed sync. For example, if setting the Sync Token to 55079 still fails to sync the item, setting the Sync Token to 55075 might successfully sync the item.
To set the Sync Token and attempt to resync an item that failed to sync, click Set Sync Token in the Zimbra Support Toolbar. The Update Sync Token dialog opens.
In the Update Sync Token dialog, enter the Sync Token to set. Click OK. To attempt to resync the item, click Send/Receive.
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.
n
Zimbra Forums. The Zimbra Forums, http://www.zimbra.com/forums, are a great place to find answers to problems and issues you may be experiencing.
n
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. Go to http://search.yahoo.com and search for other resources by entering a brief description of your problem.
Contacting Zimbra Support
Zimbra Support can be contacted at support@zimbra.com. To provide the highest level of service, please gather the following information before contacting support.
n
Steps for reproducing the problem. You will need to include steps for reproducing the problem that you are experiencing.
n
Log files. You will need to include logs generated by ZCO Logging Control, described in “Using Logging Control for troubleshooting” . These logs should only contain logging information gathered while the problem was occurring.
n
Zimbra Support Toolbar output. You will need to include any relevant Zimbra Support Toolbar output, described in “Zimbra Support Toolbar” .
Beyond the above information, include the following information if it is relevant to your problem.
n
Install logs. If you are experiencing issues with installing ZCO, please 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 will create a ZCO install log named case00012345-zco-install.log.
msiexec /i ZimbraOlkConnector-5.0.6_GA_2314_5.0.2635.6.msi /lv case00012345-zco-install.log
n
Sync error messages. If you 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 “Reviewing Sync Issues folders” .
n
Core files. If you are experiencing issues with ZCO crashing, include the automatically generated core files located in %temp%\zco-cores. If these core files have not been automatically generated, you can manually create a core dump using the instructions available at the Zimbra Wiki, located at http://wiki.zimbra.com/index.php?title=Creating_a_Core_Dump_from_a_Running_Process_using_WinDbg.
--------------------------------------------------------------------------------
Zimbra, Inc.
Copyright © Zimbra, Inc. 2005-2009. All rights reserved.
The Zimbra logo and logo type are trademarks of Zimbra, Inc. All other trademarks are the property of their respective owners.
11/4/2009
ZCS 5.0.20
 

Zimbra Connector for Outlook 5.0.20 (Rev November 2009)
Copyright © 2009 Zimbra Inc.