CommuniGate Pro MAPI Connector
Intro
Installation
SysAdmin
Objects
Transfer
Access 
Sharing 
POP 
IMAP 
Web User 
MAPI
FTP 
LDAP 
ACAP 
PWD 
Directory
Data Files
Clusters
WebApp
WebMail
Miscellaneous
Licensing
HowTo
HelpMe
The CommuniGate Pro Server can be used as a "service provider" for Microsoft Windows applications supporting the MAPI (Microsoft Messaging API). To use this service, a special Connector library (CommuniGate MAPI Connector dll) should be installed on client Microsoft Windows workstations.

The CommuniGate Pro MAPI Connector acts as a "MAPI provider". It accepts Messaging API requests from Microsoft Outlook (Outlook 97, Outlook 2000, Outlook 2002, Outlook XP and later) running in the "groupware" mode, and from other Windows applications. The MAPI Connector converts these requests into extended IMAP commands and sends them to the CommuniGate Pro Server.

The CommuniGate Pro MAPI Connector also performs data conversion between proprietary Microsoft "objects" data formats and the standard Internet data formats.

The CommuniGate Pro MAPI Connector uses TCP/IP networks and should be configured to connect to any non-TLS (clear text) IMAP port of your CommuniGate Pro server (the port 143 is the standard IMAP port).

The CommuniGate Pro MAPI Connector supports both clear text and secure (STARTTLS) connections, and it can use plain text and secure CRAM-MD5 login methods.

The CommuniGate Pro MAPI Connector contains two code parts (shared libraries). Main functionality is implemented in the library stored in the Server application directory. When the MAPI Connector connects to the CommuniGate Pro Server, the Server sends the "second part" of the MAPI Connector code to the client computer. This method allows you to deploy "regular" MAPI Connector updates without running the MAPI Connector Installer on all client workstations.

The CommuniGate Pro MAPI Connector requires a special License Key.

MAPI Connector Overview

MAPI stands for Messaging Application Programming Interface, the system component that the Microsoft corporation has included into its Windows® operating system and the API to use that component with Windows applications.

The MAPI infrastructure provides an additional level of abstraction. Windows applications do not deal directly with a groupware server (or any other "data store"). Instead, applications send Messaging requests (such as "list my mailboxes", "retrieve message number X", etc.) to the MAPI component, and the MAPI component uses the installed "Connector" modules to send those requests to an Exchange® server, to locally stored "personal folders", to a fax server, etc.

The expandable nature of the MAPI architecture allows for creation of additional "Connectors" that can interact with various server products. One of the problems that such a Connector has to solve is data format: Windows applications send data objects via MAPI to Connector modules in the so-called "MAPI object" format that has nothing in common with any Internet format. The CommuniGate Pro MAPI Connector converts the MAPI data into one of the standard Internet formats and stores the converted "messaging objects" as standard Internet messages in a CommuniGate Pro mailbox. When reading those mailboxes, the CommuniGate Pro MAPI Connector converts messages back into the "MAPI object" format and passes the converted objects back to MAPI and Windows applications (such as Outlook).

Because the standard Internet formats are used, messages stored with the CommuniGate Pro MAPI Connector can be read using any standard POP3 or IMAP mail client or the CommuniGate Pro WebUser Interface:

Installing the MAPI Connector

You need to install the MAPI Connector shared library (.dll) 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.

Creating a Mail Profile

When the CommuniGate Pro MAPI Connector is installed on a client workstation, you can create a Mail Profile that will tell Outlook and other applications to use the CommuniGate Pro MAPI services.

If you use Outlook 98 or Outlook 2000 check that it is configured to run in the "groupware mode". Start Outlook, and select the Options item from the Tools menu. The Options dialog box appears. Select the Mail Services Tab and click the Reconfigure Mail Support button to open the E-mail Service Options dialog box. Check that the Corporate or Workgroup option is selected.

Open the Mail Control Panel and click the Show Profiles button. The list of Mail profiles appears. If the CommuniGate Pro MAPI Installer has instructed you to re-create your existing Profile, select the old Profile and click the Remove button.

Click the Add button to create a new Profile. Depending on the version of the Outlook and the Mail control panel installed, you will see several dialog boxes. If you see a dialog box with the Additional Server Types option, select that option. Select CommuniGate Pro Server as the "service" or "additional server type".

You can add other services into the same Profile.

Configuring the MAPI Connector

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.

The General panel allows you to specify the MAPI Account name and other general data:

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 supported, the MAPI Connector establishes a network connection to the specified Server port, and uses the STARTTLS command to encrypt all data sent between the workstation and the Server. See the Security section for more details.

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.

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.

Note: Outlook needs to have access to the Deleted Items mailbox in each foreign Account you try to open. Make sure that such a mailbox exists there and that the Account owner has granted you the Lookup, Read, Insert, and Delete rights for that mailbox.

See the Sharing section for more details on foreign mailbox access.

Enabling Mailbox Sharing

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.

Free/Busy Information

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 the Personal Web Site area. Publicly available information in the standard vCalendar format is stored as the freebusy.vfb file in the topmost directory of your Personal Web Site. The private-type information in the Microsoft Object data format is stored as the freebusy.eml file in the Personal Web Site private directory.

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

http://domainName:port/~accountName/freebusy.vfb

Note: Make sure your CommuniGate Pro Account limits allow the MAPI Connector to store these two files with your Free/Busy information in your Personal Web Site area.

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:

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:

http://%SERVER%:8100/~%NAME%/freebusy.vfb

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:

http://mail.%SERVER%/~%NAME%/freebusy.vfb

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

http://mail.mydomain.com/~%NAME%/freebusy.vfb
where mail.mydomain.com is the name of the CommuniGate Pro Domain or its alias, that has a DNS A-record pointing to the CommuniGate Pro Server.
In this case this Search URL will work correctly only for the users of the same CommuniGate Pro Server.

The Search URL may work 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.

WebMail Integration

The Microsoft Outlook application moves the deleted messages to the Deleted Items mailbox, while the WebMail Interface moves them into the Trash mailbox. To use the same mailbox in both cases: Now both Outlook (and other MAPI applications) and the WebMail Interface will place deleted items in the same mailbox.

Communicating with Microsoft Exchange users

Outlook users that work with Exchange servers may have problems sending meeting requests to your users working with the CommuniGate Pro MAPI Connector. Meeting requests sent via an Exchange server may come in as plain text messages instead. The Exchange users should adjust the configuration of their Outlook applications:
Using Outlook Tools menu, Exchange users should open the Options dialog box. After they click the Calendaring Options button, the dialog box appears and they should enable the Send meeting requests using iCalendar by default option.

Known Limitations

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 client (Outlook) functions may be unavailable. Stalker Software 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.

CommuniGate® Pro Guide. Copyright © 1998-2002, Stalker Software, Inc.