MAPI Connector

You need to install the MAPI Connector starter code part shared library (a .dll file) on Microsoft Windows workstations. Download the MAPI Connector archive and unpack it. The unpacked folder contains the Setup.exe file.

Start the unpacked Setup.exe application to install or update your CommuniGate Pro MAPI Connector software. After successful install, the application may ask you to re-create your Mail Profile.

You can use the same Setup.exe application to uninstall the MAPI Connector software from the workstations.

The MAPI Connector Setup.exe program can be started in the silent mode (without any user interface dialogs) using the following command-line parameters:

/i	install or upgrade the MAPI connector
/r	remove the MAPI connector
/q	do not ask for profile configuration
/Q	do not display error messages

You may want to use the silent mode to install or upgrade the MAPI Connector starter code part on many workstation, using the Windows network administration methods and tools.

The cgmxui32.inf file can be used to automatically set the the MAPI Connector Account Settings and Shared Accounts. Download this file and modify it to fit your needs, then place it into the same directory where the Setup.exe application resides. The application will use it during the installation process.

When the CommuniGate Pro service is added to a Mail Profile, the service settings can be configured. Later you can open the Mail control panel, open this Profile, and open the CommuniGate Pro Server settings. You can also use the Services item in the Outlook Tools menu to open the service settings.

Server

The Server panel allows you to specify the CommuniGate Pro Server and Account data:

Server Name

The name of your CommuniGate Pro Server. This should be a domain (DNS) name that has an A-record pointing to the network (IP) address of the server.
Note: the MAPI Connector adds this name to the Account Name (see below) to send fully-qualified account names to the Server. This feature simplifies multi-domain support using a single IP address. Make sure that the specified name is either a name of some CommuniGate Pro Domain, or a name of some CommuniGate Pro Domain Alias, otherwise the Server will report the account has been moved to a remote system error.

Server Port

The network port the CommuniGate Pro Server uses for MAPI clients. This is the same port as the port used for IMAP clients.

Use a Secure (SSL/TLS) connection

If this option is selected, the MAPI Connector establishes a regular (clear text) network connection to the specified Server port, and uses the STARTTLS command to encrypt all data sent between the workstation and the Server. STARTTLS allows you to use the same server IMAP port for both clear text and secure connections.
If this option is selected, and the specified Server Port is 993 (the standard port number for secure IMAP), then the MAPI Connector establishes a secure connection to that port. This method should be used if the only port available on the server is the secure IMAP port.
See the PKI section for more details.

Use Windows Integrated Authentication (Kerberos)

Select this option if your Windows workstation is a member of a Windows/Active Directory Domain or is controlled by some other Kerberos KDC. The MAPI Connector will use your Windows username and credentials to connect to the CommuniGate Pro server.
If you want to use this option, make sure that:

• Your CommuniGate Pro Account has the Kerberos Authentication method enabled.
• Your CommuniGate Pro Domain has the proper Kerberos Keys exported from the Active Directory or Kerberos KDC.

Use the Following Authentication details

Select this option if you want to specify the Account name explicitly.

Account Name

The name of the CommuniGate Pro Account to work with. This name can be a qualified name in the accountName@domainName form. If the simple name form is used (the name does not contain the @ symbol), the MAPI Connector adds the Server Name setting value to the specified account name.

Password

The password for the specified CommuniGate Pro Account.

Remember Password

If this option is not selected, the MAPI Connector will present a Login dialog box every time it needs to connect to the Server. If this option is selected, the supplied password is stored in the MAPI Connector settings data.

Use Secure Authentication

If this option is selected, the MAPI Connector sends passwords using secure (encoded) SASL CRAM-MD5 method. The secure method does not work if passwords are stored on the Server using a one-way encrypted method (see the Security section for more details). In this case this option should be disabled, and the MAPI Connector will send passwords in clear text.
Note: if you need to send passwords in clear text while connecting to the Server via public networks, enable the Use a Secure connection option, so all information is encrypted.

Account Settings

The Account Settings dialog box can be opened by pressing the Account Settings button on the Server panel. The box allows you to specify the MAPI Account name and other general data:

Connection

The Connection panel allows you to select your network connection method.

Offline

When working in the Offline mode (without a server connection, and using the local message cache only), you may want to tell the Connector to start in the Offline mode.
This will eliminate connection attempts on startup (to avoid bringing up your modem, for example).

Advanced

The Advanced panel allows you to specify other CommuniGate Pro Accounts you want to work with.

Use the Add and Remove buttons to specify the names of other CommuniGate Pro Accounts. If you want to access an Account in a different Domain, specify the full name: accountName@domainName.

The Account owners must grant you Mailbox Access Rights, otherwise you won't be able to see and open Mailboxes in those Accounts. See the Mailboxes section for more details on foreign Mailbox access.

The Synchronization settings allow you to override the selection of folders to work with in the Offline mode.

Include all folders in Send/Receive operation

Use this option to select all the account folders for download, regardless the selection in Outlook -> Tools -> Options -> CommuniGate Pro.

Always download entire message

With this option checked the Connector will download the entire message bodies (versus Headers Only).

Use the Cache files root folder settings to specify where the MAPI Connector should store its local cache. The local cache is used for most MAPI Connector operations, it also allows you to use the MAPI applications (such as Outlook) in the off-line mode.

Local Outlook Application Data folder

Use this option to store the cache files in the default location on your workstation. The cache file will be available on this workstation only.

Global Outlook Application Data folder

Use this option is you use Windows roaming features and plan to use your Outlook application from several workstations.
Note: the cache files can be quite large (they may even store a complete copy of all your server-based mailbox data, depending on the Connector settings). If the cache file becomes large, you can experience delays when you are logging into the workstation, as the workstation needs to copy all roaming data.

Custom

Use this option if you want to store the cache files in a custom location. For example, you may want to choose a shared folder on a file server to avoid delays caused by roaming.

You can specify Access Control List for your mailboxes to grant access to those mailboxes to other CommuniGate Pro users.

Select a mailbox in the Outlook Folder List, and use the Properties menu item to open the Properties dialog box. Open the Permissions panel:

Use the Add and remove buttons to specify the Accounts and other identifiers to specify those who should have access to this mailbox.

Select an identifier in the list and use the checkboxes to grant required access rights to this identifier. See the Mailboxes section for more details on mailbox ACLs.
Note: a user needs to have the Admin Access Right in order to specify the default Mailbox (Folder) View.

The Free/Busy information is a file specifying when the person is busy, free, out of the office, etc. This information is usually made publicly available, so other users can access it when planning their meetings, scheduling appointments, etc. To compose the Free/Busy data, the groupware client application collects data from user Calendar(s), and merges it into one Free/Busy schedule.

Posting Free/Busy Information

The MAPI Connector stores your Free/Busy information in your Account File Storage.
Publicly available information in the standard vCalendar format is stored as the freebusy.vfb file in the topmost directory of your File Storage.

Note: Make sure your CommuniGate Pro Account Settings allow the MAPI Connector to store a file with your Free/Busy information in your File Storage.

This feature allows users of Outlook and other calendaring clients to access your File Storage via HTTP and retrieve your Free/Busy information. The URL for the CommuniGate Pro Connector user Free/Busy information is

Accessing Free/Busy Information for Other Users

In order to process Appointments and Meetings, the Outlook application on the client machine should be able to access the Free/Busy information of other users. This operation is not implemented via the MAPI Connector and should be done by the Outlook application itself. To configure your Outlook application:

• Install the Microsoft Web Publishing Wizard (it can be downloaded from the www.microsoft.com Web site).
• Select Options from the Tools menu to open the Options dialog box.
• Click the Calendar Options button to open the Calendar Options dialog box.
• Click the Free/Busy Options button to open the Free/Busy Options dialog box.
• Enter the http://%SERVER%/~%NAME%/freebusy.vfb URL string into the Search field. (read all the notes below).
• Click the OK buttons to close all dialog boxes.

This option will be used by the Outlook application when it needs to retrieve the Free/Busy information for an E-mail user. The application substitutes the %SERVER% symbols with the domain part of the user E-mail, and the %NAME% symbols with the username part of the user E-mail, so for the E-mail address john@myserver.dom the Outlook will use the http://myserver.dom/~john/freebusy.vfb URL to retrieve John's Free/Busy schedule.

Note: the suggested Search URL will work only if your CommuniGate Pro Server accepts WebUser Interface connections on the port 80. If it accepts them on the default port 8100, or on any other non-standard port, the Search URL must include that port:

Note: the suggested Search URL will work only if your CommuniGate Pro Domains have names that have A-records pointing to the CommuniGate Pro server. Often, the DNS system does not contain any A-record for your mydomain.dom Domains, or those records point to a different system (company Web server), while the CommuniGate Pro Server addresses are specified as mail.mydomain.com, or cgate.mydomain.com, or mx.mydomain.com or similar DNS A-record(s). In this case the Search URL must be modified to use the proper domain names:

Note: if your CommuniGate Pro server is serving only one Domain, then you can specify the Search URL as:

where mail.mydomain.com is the name of the CommuniGate Pro Domain or its alias. This should be a name of a DNS A-record pointing to the CommuniGate Pro Server.

Search URLs specified above allow users to retrieve Free/Busy information for the users of the same CommuniGate Pro system.

The Search URL may be used to retrieve the Free/Busy Information for users of other CommuniGate Pro Servers, as long as the Search URL correctly represents their Free/Busy file URLs. To overwrite the Search URL and specify a different (correct) path to some remote user Free/Busy file, create a Contact record for that user, click on the Details tab and enter the correct FreeBusy file URL into the Internet Free-Busy Address field. See the Microsoft Outlook manual for more details on these settings.

The MAPI Connector allows you to specify the server-side Rules to process mail coming to your Account.

Use the Tools->CommuniGate Pro menu to open the Rules editor window:

Click the New button to create a new Rule. New Rule has no condition and no action.

Click the Add button to add Rule conditions and actions:

See the Automatic Rules section for more details.

The MAPI connector allows you to specify Server-side Rules, including the Rules that can store incoming messages in an encrypted form.

You may also want to improve security for certain messages received and stored on the Server in clear-text.

Right-click on the selected message in Outlook. A pop-up menu will open:

When you select the Encrypt Message item, the MAPI Connector will send your default Certificate (containing your Public Key) to the Server. The Server will use that Certificate to encrypt the selected message. It will be stored on the Server in the encrypted S/MIME format - as if the message sender has sent it encrypted.

If you want to read Encrypted messages using your MAPI clients (Outlook) and the WebUser Interface, make sure that your Windows desktop system and the WebUser Interface have the same Private Keys and Certificates installed. You can either generate a key and Certificate in the WebUser Interface and then export them to your Windows desktop system, or you can export your keys from the Windows desktop system and import them into your WebUser Interface settings.

The MAPI connector works as a liaison between MAPI applications (such as Microsoft Outlook) and the CommuniGate Pro Server. The problem a user can experience with its client, can be a bug or feature of that client, or a problem in the MAPI Connector or Server software. To help investigate the problem, the MAPI Connector can generate a detailed Log of all operations it was requested to perform. You can examine that Log yourself or send it to CommuniGate Systems technical support.

Open the Troubleshooting panel in the MAPI Connector ("CommuniGate Pro Service") setup box:

The panel displays the versions of both MAPI Connector software components: the starter code library installed on your desktop computer and the server code library retrieved from the CommuniGate Pro Server.

Select the Enable Logging option to start MAPI Connector log recording. The MAPI Connector Log keeps only the last records, so the Log file does not exceed the size specified in the Maximum Log File Size setting.

Use the checkbox controls to enable logging for various MAPI Connector components.

Click the Show Me Log File button to open a file directory window the Log file is stored in. You can use this feature to E-mail the Log file to CommuniGate Systems technical support.

Click the Delete Log File to clear the Log file.

Use the Compatibility options to tune up the MAPI Connector operation for mixed environments.

Send in Outlook native message format

In some rare cases special messages (such as Task requests or forwarded Contacts) sent via the MAPI Connector in the Internet format may be interpreted incorrectly by Outlook Exchange (or Outlook IMAP) users. Checking this option may help to solve the problem.

Send in Outlook 2000 compatible format

Older versions of Outlook may have problems interpreting Calendar and Contact items in the format used by newer versions of Outlook. Check this option to use older format for these items.

Send in Exchange 5.5 compatible format

Meeting requests in formats used by newer versions of Outlook may be incorrectly interpreted by Exchange 5.5 servers. Check this option if any of your correspondents use this version of Exchange server and have problems accepting your meeting requests.

Conservative mass deletion

In some configuration the Outlook Autoarchive function may remove messages in large portions. To avoid this problem, select this option.

Always convert RTF to HTML

Selecting this option causes the text/rtf MIME parts in outgoing messages to be converted to HTML, which is understood by the larger number of mail client applications.

Do not display "Server transaction in progress..." dialog

During long server transactions the Connector displays a progress indicator window. If you don't want that select this option.

Show reports in Outlook native format

Outlook can use a special form to display non delivery notification messages, which provides interface for re-sending of the failed messages. For this feature to work correctly the non-delivery report should contain the full body of the failed message, which is not always the case.

Do not respond to requests for read receipts

The sender of a message may request a receipt to be sent back to him when you open a message for reading. To ignore such requests select this option.

No history uploads for large messages

To fulfill Outlook requests to set some extended property on a message the MAPI connector may re-upload modified message back to the server. This may take quite a while for large messages. To disable this kind of activity check this option.

Erase messages immediately, do not mark for deletion

To increase performance, by default messages are not removed immediately but rather are marked for deletion and removed physically when the folder containing them is closed. If the folder is accessed by several clients simultaneously, these items marked for deletion may still appear in those clients and confuse users. To avoid that you can check this option.

Refresh connection every minute

Some NAT and anti-virus/spam firewalls are very aggressive in terminating TCP connections which they assume to be idle. Closing IMAP sessions this way on the TCP level may confuse Outlook. With this option checked, the MAPI Connector will produce some minimal data exchange on the connection to the CommuniGate pro server, so that connection does not appear idle to the firewall.

Restrict search to downloaded items only

Searching through some message attributes may require downloading items to the client. This may take quite a while for large message store. With this option checked only those items that were previously cached by the MAPI Connector will be searched.

The protocols and APIs the MAPI Connector implements are not the Internet standards, but API from the Microsoft® Corporation. Those APIs are not fully documented, and as a result, some minor client (Outlook) functions may be unavailable. CommuniGate Systems is working on solving these problems, and the MAPI Connector updates are released on a regular basis.

The special Known MAPI Problems site lists all reported and known problems and provides the status update on them. Please consult this site first if you have any problem with the MAPI Connector functionality.