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.jsis 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 ZimbraCollaboration 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.
From the administration console, copy the
ZmCustomizeMsi.jsfile and the ZCOMSIfile to a folder on a computer running the Windows platform.Open the Windows command prompt in that folder.
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 Securityfor more information about connection security.
Press Enter.The ZCO MSI file is modified
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.
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 provider1: 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,
you need to set
--usezimbrafreebusyor-zfbto0and create a new ZCO installer.Users need to uninstall the current version of ZCO.
Users must then reinstall ZCO with the MSI which has
--usezimbrafreebusyor-zfbset to0.
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 ribbon → Sync Global Address List → Update Global Address List → Update 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-1DBs are never compacted
Attempts to compact DBs on each Outlook login
1-300Number 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,-acdbms10-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
.dbfile exceeds 256 MB.- Minimum ZCO DBs' size required to initiate autocompaction
Switch
Value
Description
--autocompactzdbminsize,-aczdbms200-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
.zdbfile exceeds 1024 MB.- Display to users, auto compact progress information
Switch
Value
Description
--autocompactshowprogressui,-acspuiThe user does not see the progress bar regarding the auto compaction.
1The 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.
From the administration console, click Downloads link.
Open the
Zimbra Connector for Outlook Branding MSI.vbs(Visual Basic) file.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 |
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:
Share notification email for a compressed log archive file placed in the user’s briefcase folder under
ZCOLogsfolder, shared with admin user.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.
|
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
Using Middle Name Search
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 AzamMiddle Name: NLast 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\ |
