Configuring and Integrating MAPI

(1)

The Basics of MAPI 3 The MAPI User Experience Monitor in SAM 4

Troubleshooting MAPI 7

This document includes basic information about MAPI and its role with SolarWinds SAM.

(2)

Copyright© 1995-2012 SolarWinds. All rights reserved worldwide. No part of this document may be reproduced by any means nor modified, decompiled, disassembled, published or distributed, in whole or in part, or translated to any electronic medium or other means without the written consent of SolarWinds. All right, title and interest in and to the software and documentation are and shall remain the exclusive property of SolarWinds and its licensors. SolarWinds Orion™, SolarWinds Cirrus™, and SolarWinds Toolset™ are trademarks of SolarWinds and SolarWinds.net® and the SolarWinds logo are registered trademarks of SolarWinds All other trademarks contained in this document and in the Software are the property of their respective owners.

SOLARWINDS DISCLAIMS ALL WARRANTIES, CONDITIONS OR OTHER TERMS, EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, ON SOFTWARE AND DOCUMENTATION FURNISHED HEREUNDER INCLUDING WITHOUT LIMITATION THE WARRANTIES OF DESIGN, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL SOLARWINDS, ITS SUPPLIERS OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, WHETHER ARISING IN TORT, CONTRACT OR ANY OTHER LEGAL THEORY EVEN IF SOLARWINDS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Microsoft® and Windows 2000® are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

(3)

The Basics of MAPI

Messaging Application Programming Interface (MAPI) is a Microsoft Windows program that enables you to send email

from within a Windows application. Programs that use MAPI include word processors, spreadsheets, and graphics applications.

Programmers who are using Microsoft's Active Server Page (ASP) technology access MAPI by using Microsoft's

Collaboration Data Objects (CDO). The CDO library comes with Microsoft's Internet Information Server (IIS). MAPI

functions can be accessed by Visual Basic programmers.

CDO - http://www.microsoft.com/download/en/details.aspx?id=1004

A "session" is a specific connection between the client and the MAPI program. MAPI defines the following three services:

 Address book: A database that contains addressing information.  Transport: Supports communication between different devices.  Message store: Stores messages that consists folders and subfolders.

Simple MAPI is a subset of 12 functions which enable developers to add basic messaging functionality. Extended MAPI allows complete control over the email system.

(4)

4  Index

The MAPI User Experience Monitor in SAM

This component monitor sends an email from your SMTP mail server to your Microsoft Exchange Server Mailbox and measures the time it takes to complete the trip. You can use this component monitor to measure the performance of Outlook. This response time is measured in milliseconds.

The Exchange Server computer uses port 135 for client connections to the RPC endpoint mapper service. After a client connects to a socket, the Exchange Server allocates the client two random TCP ports above 1024 used to communicate with the directory and the information store.

For a complete list of network ports used by Microsoft Server Products, refer to the following article: http://technet.microsoft.com/en-us/library/bb331973.aspx

What credentials should a user use?

User credentials must be valid for both the Exchange server mailbox and the SAM server. This means that the SAM server and Exchange server must be in the same domain and the probe must use domain credentials.

Why does the profile have to be able to log in to the SAM server?

Because the probe uses an external .exe module – SolarWinds.APM.MAPI.exe. Meaning, user impersonation on the SAM server is needed to have ability to run external process.

Install the MAPI Client on the SolarWinds SAM Server

This component monitor requires you to install the Microsoft Exchange Server MAPI Client and Collaboration Data Objects on your SolarWinds SAM server. You can download the MAPI Client from:

The Microsoft Download Center. http://www.microsoft.com/downloads/details.aspx?FamilyID=E17E7F31-079A-43A9-BFF2-0A110307611E

This component monitor does not compute a statistic. The response time is the difference between the time SolarWinds SAM sends the email and the time that it is received by the recipient. Following is an illustration of the MAPI monitor. To expose the fields, as illustrated below, click the [+] to the left of the component monitor name.

(5)

What the MAPI monitor does:

1. This component monitor waits for the email to arrive based on the default job timeout of 20 minutes. If the email does

not arrive within this period, SolarWinds SAM marks the monitor as Down.

2. The monitor goes through the following steps with respect to the mail flow:

a. Sends an email to the user mailbox via SMTP. The email has a unique temporary subject name that starts with APM_prefix.

b. Connects to the user mailbox through MAPI, then searches the emails by Subject.

c. If it does not find the email it is looking for, it waits and then searches again. It will stop when: 1. It finds the email;

2. The timeout is reached;

3. The maximum number of attempts is reached.

d. Once it finds the email, the monitor deletes it from the user inbox.

e. The monitor collects the total round trip time for the email and compares it with the thresholds set.

f. Once it knows the round trip time, status is given according to where it falls with regard to the thresholds set. If the email is not found within the timeout or the maximum number of attempts, or SMTP or MAPI reported an error, SolarWinds SAM will mark the monitor as down.

3. Emails are posted using SMTP. If the MAPI probe works, emails will be deleted successfully, if not, emails will

accumulate.

4. It is not currently possible to use the monitor without SMTP and send the email from the same server the monitor is

running on via MAPI.

Field Descriptions of the MAPI Monitor: Description

This field provides a default description of the monitor. You have the ability to override the default description by adding to or replacing the text, which will then be automatically saved. The variable to access this field is

${UserDescription}.

Enable Component

Determines whether the component is enabled.

Credential for Monitoring

Select a credential that is both a user who can log on to the SolarWinds SAM server, and that has an Exchange account on the MAPI server. If the credential you need is not already present in the credentials list, use the Quick

Credentials section to add a new credential. Send Email From

This field allows you to specify the From address of the test email message.

Send Email To

This field allows you to specify the recipient of the test email message. The recipient should have a mailbox on the MAPI server you are monitoring.

MAPI Profile Name

Allows you to specify the name of the MAPI profile

SMTP Server

(6)

6  Index

SMTP Port

This field is the port number used for SMTP sessions. The default value is 25.

Use Credentials for SMTP

This checkbox allows you to use the user name and password from Credentials for Monitoring to connect to SMTP servers that support or require authentication.

SMTP Encryption

This list allows you to select an encryption protocol to connect to SMTP servers that support SSL or TLS encryption.

Response Time Warning Threshold

This field allows you to set the warning threshold conditions based on the response time. The response time is the time in milliseconds it takes SolarWinds SAM to determine that a component is not Down and to retrieve any statistical data.

Response Time Critical Threshold

This field allows you to set critical threshold conditions based on the response time. The response time is the time in milliseconds it takes SolarWinds SAM to determine that a component is not Down and to retrieve any statistical data.

User Notes

(7)

Troubleshooting MAPI

The following procedures will help you troubleshoot MAPI issues relating to SAM

Note: Do not use the same mailbox for multiple MAPI UX monitors. Doing so can cause the MAPI monitor to intermittently

fail.

MAPI Probe Diagnostic Checklist

Install CDO or Outlook

 CDO can be found here: http://www.microsoft.com/download/en/details.aspx?id=1004. If you would like to install CDO, uninstall your entire MS Office installation. Uninstalling Outlook only is not sufficient.

 The MAPI probe may be unstable when running with Outlook installed. If this is the case, uninstall Office then download and install CDO.

Check the MAPI profile

 The MAPI profile does not need to exist. The probe should create it and also update the existing profile with the required settings. However, there may be issues with an existing or created profile. The default Outlook profile is called Outlook.

 If this profile does not work, create a profile with the MFCMapi free tool, availabe at: http://mfcmapi.codeplex.com/.

1. In the MFCMapi tool, navigate to Profile > Advanced Profile > Launch Profile Wizard, keeping the defaults on the first dialog.

2. Set the profile as default.

3. Update the profile name of the newly created profile in the MAPI probe.

 Use MFCMapi to find the profile name: Navigate to Profile > Show Profiles for verification.

Check probe settings

 Check that Send Email To: is correctly filled out in the component settings.

 The Mapi Profile Name must match the actual profile name. Use the MFCMapi tool if you are not sure about the name.

 Credentials used for the probe must be eligible to open the mailbox. It is required to add the user to the local Administrators group, otherwise the probe can fail with insufficient privileges.

Mailbox recommendations

 Use a clean mailbox created for monitoring purposes. A mailbox full of email is problematic as it takes a lot more time for the probe to search through all of the emails. The MAPI probe deletes obsolete, undeleted messages sent by the probe in the past to keep the mailbox clean.

(8)

8  Index

Advanced Troubleshooting

SolarWinds.APM.MAPI.exe Command Line Arguments

To analyze issues with the MAPI probe more closely, run the MAPI executable from the command line. The following arguments can be used:

Command Explanation

-s <subject> _{The subject text of searched in an email. Use quotes for a subject} containing spaces.

-server <server_name> _{Server hostname / IP address.}

-t <timeout> _{Timeout in ms for watchdog.}

-p <profile_name> _{Exchange profile name.}

-u <user_name> _{Exchange user name}

-attempts <count> _{Maximum number of search attempts.}

-debug _{Turns on debug logging.}

-removeall _{Remove all historical messages from the MAPI probe. Messages from} the MAPI probe get stuck in the mailbox if the probe fails to delete them.

-w _{Wait time between search attempts.}

New in SAM 5.0:

-subjectmatchsubstring: This enables a substring subject match. The target mail subject is expected to match the substring of the subject setting. An exact match is expected by default. This is useful for matching emails returned by bouncers, which can add “Re: “ to the mail subject.

Note: This command is not listed in configuration file.

For example:

SolarWinds.APM.MAPI.exe -debug -s "test subject" -u domain\user.name -server exchange -p Outlook -t 10000

Important: Run the executable as the user owning the mailbox. To do this, start a new cmd.exe and run the following command.

runas /user:domain\user.name cmd.exe

(9)

The MAPI probe is also configurable via the SolarWinds.APM.MAPI.exe.xml file. Settings in this file take precedence over any command line arguments. See the following:

<logdirectory>c:\logs</logdirectory> <logenable>false</logenable> <logkeepall>true</logkeepall> <enablewatchdog>true</enablewatchdog> <mapimaxwaitlogoff>2500</mapimaxwaitlogoff> <dologoff>true</dologoff>  </settings> Command Explanation

Logdirectory _{Path to the directory where logs from the MAPI executable will be written. This} directory must exist otherwise no logs will be written.

Logenable _{Enable log file logging.}

Logkeepall _{Set false for deleting the log file after a successful run, (i.e. email was found and} deleted; all log files are preserved by default (true).)

Enablewatchdog _{Enable or disable watchdog which kills the MAPI processing thread if it does not finish} in a given time. Prevents processing for a long time.

Mapimaxwaitlogoff _{Number of milliseconds to wait for logoff before the MAPI process ends. This setting is} used after an error during MAPI processing and between attempts to retrieve probe mail.

Dologoff _{Set to false to skip logoff and closing the MAPI session.}

Debug _{True for debugging information and detailed logging to the log file or console.}

Removeall _{Remove all obsolete messages from the mailbox matching the}_{subjectpattern} regular expression. The SAM probe always tries to enable this setting from the command line.

Subjectpattern _{Regular expression pattern for deleting obsolete probe messages. Use together with} removeall =true

(10)

10  Index

New in SAM 5.0 (not listed in the configuration file):

subjectmatchsubstring – true/false setting (false by default) to match just the substring of the subject. This is useful for matching emails returned by bouncers, which can add “Re: “ to the mail subject.

During initial analysis, it is typically required to update logdirectory (or create C:\logs) and set logenable to true. Other arguments are passed from the command line.