|
Version 6.3 |
|
| ||||||||||||||||||||||
MAPI Connector OverviewMAPI 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 very little 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). The CommuniGate Pro MAPI Connector acts as a "MAPI provider". It accepts Messaging API requests from Microsoft Outlook (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 (SSL/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).
The starter code part should be installed on Windows workstations. It provides
the configuration interface and it is used to connect to the CommuniGate Pro server.
The main MAPI Connector functionality is implemented as a shared library stored in the Server application directory, and it is called the server code part.
Installing the MAPI ConnectorYou 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:
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. To set the language of the MAPI-Connector interface the cgmxp32.ini file can be used. Place it into the same directory where the setup.exe installer resides. During installation process the file will be copied to the C:\Windows directory (if MAPI-Connector was installed earlier, you can do this manually). The language of the MAPI-Connector interface will be set according to the OS localization. To automate MAPI-Connector configuration the cgmxui32.inf file can be used. Modify this file to fit your needs (the description of the settings is within the file), then place it into the same directory where the setup.exe installer resides. During installation process the file will be copied to the C:\Windows directory (if MAPI-Connector has been installed earlier, you can do this manually). To create an Outlook profile with the predefined MAPI-Connector settings run command prompt as Administrator and execute the following command: regsvr32.exe cgmxui32.dll /i:16 For Outlook 32-bit cgmxui32.dll resides in C:\Windows\SysWOW64 For Outlook 64-bit cgmxui32.dll resides in C:\Windows\System32 As the result, the Outlook profile with the name username_CGATE (where username is the name of the currently logged in user) will be created with the predefined MAPI-Connector settings. If, as the result of the command execution, an error message appears, make sure, that the command is run as Administrator, and the cgmxp32.inf file exists in the C:\Windows directory. Alternative way not requiring Administrator rights: Run ex2cgp, matching Outlook bitness, with the following parameters: ex2cgp.exe profileonly full_path_to_cgmxui32.inf If you need the created profile to be set as default, add "default " in the end. Example:
Creating a Mail ProfileWhen 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 ConnectorWhen 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. ServerThe Server panel allows you to specify the CommuniGate Pro Server and Account data:
Account SettingsThe 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:ConnectionThe Connection panel allows you to select your network connection method.
AdvancedThe 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.
Enabling Mailbox SharingYou 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.
DelegationThe MAPI Connector supports the "delegation" feature: users can send E-mails and Calendar invitations "on behalf of" or "as" other users. To grant some user delegation rights for your Account,grant that user the Read (Select) right for your INBOX. Free/Busy InformationThe 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 InformationThe 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 ishttp://domainName:port/~accountName/freebusy.vfb
Accessing Free/Busy Information for Other UsersIn 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 implemented via the MAPI Connector, but also may 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. 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. Working OfflineWhen you work in the Offline mode, the MAPI Connector does not have access to the messages stored on the CommuniGate Pro server. To be able to work productively, you need to make sure that the messages you need are stored in the MAPI Connector local cache. You specify the cache options on the per-Mailbox (per-folder) basis. Use the Options item in the Outlook Tools menu to open the Options dialog box. Then open the CommuniGate Pro panel:Select the folder you need to work with when you use the Offline mode, and select the downloading method. If you select to download the entire message, the folder name will be shown in bold, if you choose to download message headers only, there will be only a check mark next to the folder name. Use the Outlook Tools->CommuniGate Pro Server menu to synchronize the changes you do in the Offline mode with the CommuniGate Pro server. Synchronization takes place when the Send/Receive operation is initiated (manually or automatically, based on the schedule).
Configuring Automatic RulesThe 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. WebMail IntegrationThe MAPI Connector employs the user WebMail (WebUser Interface) settings. It instructs the MAPI applications (such as the Microsoft Outlook) to use the same names for "Special" Mailboxes. As a result MAPI applications and the WebUser Interface use the same Trash or Deleted Items Mailbox to store removed messages, use the same Mailbox as the Main Calendar Mailbox, etc. The MAPI Connector also retrieves the user Domain Mail Trailer setting. The content of that setting is added to all non-encrypted and not-signed text messages submitted via the MAPI Connector. The values specified via the Account Settings panel are stored in the WebUser Settings, so both the WebUser Interface and MAPI sessions use the same From:, Reply-To:, and Organization values. 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:
Real-Time CommunicationsThe MAPI Connector allows Outlook users to employ Real-Time (VoIP, etc.) functions of the CommuniGate Pro Server. Outlook users can initiate a phone call using the telephone number specified in a Contact item. Right-click a Contact record to open a pop-up menu and select the Call using CommuniGate Pro item:You can also use the CommuniGate Pro Server submenu in the Tools menu. A dialog box with the Contact name and phone number appears: You can type a different phone number in the second field. That number will be used for this call only, it will not be stored with the Contact Item.Click the Start Call button to initiate a call. All your SIP devices will start to ring immediately. Answer this call on any device, and the Server will instruct it to initiate a call to the selected phone number. The dialog box has a field displaying the call status:Server-side EncryptionThe 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. TroubleshootingThe 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.
Known LimitationsThe 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. |