ibm tivoli netcool/omnibus probe for microsoft exchange

IBM® Tivoli® Netcool/OMNIbus Probe forMicrosoft Exchange Web Services2.0

Reference GuideSeptember 25, 2020

IBM

SC27-8743-02

Notice

Before using this information and the product it supports, read the information in Appendix A, “Noticesand Trademarks,” on page 35.

Edition notice

This edition (SC27-8743-02) applies to version 2.0 of IBM Tivoli Netcool/OMNIbus Probe for Microsoft Exchange WebServices and to all subsequent releases and notifications until otherwise indicated in new editions.

This edition replaces SC27-8743-01.© Copyright International Business Machines Corporation 2016, 2020.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

About this guide.................................................................................................... vDocument control page................................................................................................................................ vConventions used in this guide.................................................................................................................... v

Chapter 1. Probe for Microsoft EWS........................................................................1Summary...................................................................................................................................................... 1Installing probes.......................................................................................................................................... 2Configuring the probe.................................................................................................................................. 2

Specifying a truststore file......................................................................................................................2Specifying an authentication mode....................................................................................................... 3

Running the probe........................................................................................................................................6Data acquisition........................................................................................................................................... 6

Filtering emails....................................................................................................................................... 7Extracting plain text from the body of emails containing HTML........................................................... 8Deleting emails after processing............................................................................................................9Event stream parsing as a single line.....................................................................................................9Event stream parsing for multiple lines...............................................................................................10Line parsing with quotation marks.......................................................................................................12Line parsing with consecutive unquoted white spaces.......................................................................12Formatting multi-line elements........................................................................................................... 12Peer-to-peer failover functionality...................................................................................................... 13Stream capture.....................................................................................................................................13

Properties and command line options...................................................................................................... 13Properties and command line options provided by the Java Probe Integration Library (probe-sdk-

java) version 12.0................................................................................................................................. 23Elements.................................................................................................................................................... 26Error messages.......................................................................................................................................... 29Known issues............................................................................................................................................. 33

Appendix A. Notices and Trademarks................................................................... 35Notices....................................................................................................................................................... 35Trademarks................................................................................................................................................ 36

iii

About this guide

The following sections contain important information about using this guide.

Document control pageUse this information to track changes between versions of this guide.

The IBM Tivoli Netcool/OMNIbus Probe for Microsoft Exchange Web Services documentation is providedin softcopy format only. To obtain the most recent version, visit the IBM® Tivoli® Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/?lang=en#!/SSSHTQ/omnibus/probes/common/Probes.html

Table 1. Document modification history

Documentversion

Publicationdate

Comments

SC27-8743-00 November 24,2016

First IBM publication.

SC27-8743-01 December 13,2019

“Known issues” on page 33 added.

SC27-8743-02 September 25,2020

Updated for version 2.0 of the Probe for Microsoft Exchange WebServices.

Support added for OAuth2 authentication.

Support added for proxy connection.

“Summary” on page 1 updated.

“Specifying an authentication mode” on page 3 added.

Descriptions for properties added to “Properties and command lineoptions” on page 13.

Descriptions for new error messages added to “Error messages” onpage 29.

Fixes:

Version 2.0 of the Probe for Microsoft Exchange Web Servicesaddresses the following APARs:

IJ18132: ILLEGAL CHARACTER ENTITY DETECTED message inlog file.

Conventions used in this guideAll probe guides use standard conventions for operating system-dependent environment variables anddirectory paths.

Operating system-dependent variables and pathsAll probe guides use standard conventions for specifying environment variables and describing directorypaths, depending on what operating systems the probe is supported on.

© Copyright IBM Corp. 2016, 2020 v



For probes supported on UNIX and Linux operating systems, probe guides use the standard UNIXconventions such as $variable for environment variables and forward slashes (/) in directory paths. Forexample:

$OMNIHOME/probes

For probes supported only on Windows operating systems, probe guides use the standard Windowsconventions such as %variable% for environment variables and backward slashes (\) in directory paths.For example:

%OMNIHOME%\probes

For probes supported on UNIX, Linux, and Windows operating systems, probe guides use the standardUNIX conventions for specifying environment variables and describing directory paths. When using theWindows command line with these probes, replace the UNIX conventions used in the guide with Windowsconventions. If you are using the bash shell on a Windows system, you can use the UNIX conventions.

Note : The names of environment variables are not always the same in Windows and UNIX environments.For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX and Linuxenvironments. Where such variables are described in the guide, both the UNIX and Windows conventionswill be used.

Operating system-specific directory namesWhere Tivoli Netcool/OMNIbus files are identified as located within an arch directory under NCHOME orOMNIHOME, arch is a variable that represents your operating system directory. For example:

$OMNIHOME/probes/arch

The following table lists the directory names used for each operating system.

Note : This probe may not support all of the operating systems specified in the table.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

Red Hat Linux® and SUSE systems linux2x86

Linux for System z linux2s390

Solaris systems solaris2

Windows systems win32

OMNIHOME locationProbes and older versions of Tivoli Netcool/OMNIbus use the OMNIHOME environment variable in manyconfiguration files. Set the value of OMNIHOME as follows:

• On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus.• On Windows, set %OMNIHOME% to %NCHOME%\omnibus.

vi IBM Tivoli Netcool/OMNIbus Probe for Microsoft Exchange Web Services: Reference Guide

Chapter 1. Probe for Microsoft EWS

The IBM Tivoli Netcool/OMNIbus Probe for Microsoft Exchange Web Services (EWS) processes emailsfrom either Microsoft Exchange Server or Microsoft Exchange Online and sends them as Netcool/OMNIbus events to a Tivoli Netcool/OMNIbus ObjectServer. The probe takes advantage of the ExchangeWeb Services API to integrate with the Exchange Server or Exchange Online.

Note : The Probe for Microsoft Exchange Web Services is only supported on Netcool/OMNIbus V8.1.

This guide contains the following sections:

• “Summary” on page 1• “Installing probes” on page 2• “Configuring the probe” on page 2• “Running the probe” on page 6• “Data acquisition” on page 6• “Properties and command line options” on page 13• “Elements” on page 26• “Error messages” on page 29

SummaryEach probe works in a different way to acquire event data from its source, and therefore has specificfeatures, default values, and changeable properties. Use this summary information to learn about thisprobe.

The following table summarizes the probe.

Table 3. Summary

Probe target Microsoft Exchange Server 2010 SP2 and above, 2013, and2016, and Microsoft Exchange Online by accessing MicrosoftEWS.

Probe executable name nco_p_ews

Package version 2.0

Probe supported on For details of supported operating systems, see the followingRelease Notice on the IBM Software Support website:

http://www-01.ibm.com/support/docview.wss?uid=swg21993573

Properties file $OMNIHOME/probes/arch/ews.props

Rules file $OMNIHOME/probes/arch/ews.rules

Requirements For details of any additional software that this probe requires,refer to the README file that is supplied in its downloadpackage.

Connection method Web Services

© Copyright IBM Corp. 2016, 2020 1



Table 3. Summary (continued)

Multicultural support Available

Peer-to-peer failover functionality Available

IP environment IPv4 and IPv6

Federal Information ProcessingStandards (FIPS)

IBM Tivoli Netcool/OMNIbus uses the FIPS 140-2 approvedcryptographic provider: IBM Crypto for C (ICC) certificate 384for cryptography. This certificate is listed on the NIST website athttp://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm. For details about configuring Netcool/OMNIbus for FIPS 140-2 mode, see the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide.

Installing probesAll probes are installed in a similar way. The process involves downloading the appropriate installationpackage for your operating system, installing the appropriate files for the version of Netcool/OMNIbusthat you are running, and configuring the probe to suit your environment.

The installation process consists of the following steps:

1. Downloading the installation package for the probe from the Passport Advantage Online website.

Each probe has a single installation package for each operating system supported. For details abouthow to locate and download the installation package for your operating system, visit the following pageon the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.html

2. Installing the probe using the installation package.

The installation package contains the appropriate files for all supported versions of Netcool/OMNIbus.For details about how to install the probe to run with your version of Netcool/OMNIbus, visit thefollowing page on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.html

3. Configuring the probe.

This guide contains details of the essential configuration required to run this probe. It combines topicsthat are common to all probes and topics that are peculiar to this probe. For details about additionalconfiguration that is common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and GatewayGuide.

Configuring the probeAfter installing the probe you need to make various configuration settings to enable the probe to connectto Microsoft EWS.

Specifying a truststore fileIf you are using a TLS connection to an Exchange Server with a TLS certificate not issued by a knowncertificate authority (CA), you must generate a truststore file to store the Certificate Authority (CA)

2 IBM Tivoli Netcool/OMNIbus Probe for Microsoft Exchange Web Services: Reference Guide

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm





certificate used to verify the Exchange Server. After that you will need to update the truststore property inthe ews.props file.

You can generate the truststore file using the Java keytool utility, which is located in the followingdirectory:

$NCHOME/platform/arch/jre_1.8.0/jre/bin

To generate the truststore file in JKS file format, use the following steps:

1. Use the keytool utility to generate the keystore by running the following command:

keytool -import -alias server_certificate -file certificate_file -keystoretruststore_name

where:

• server_certificate is an alias (any name will do, for example: "ews").• certificate_file is the Certificate Authority (CA) certificate for the Exchange Server.• truststore_name is the name of the output truststore file, for example, truststore_ews.

2. When prompted, enter a password for the truststore file and make a note of it.3. Store the truststore file in a directory on the machine where the probe is located. For example:

$OMNIHOME/probes/arch/

After generating the truststore file, specify the following properties in the ews.props file:

• TrustStoreFile - Use this property to specify the location of the keystore file created in the stepsabove.

• TrustStorePassword - Use this property to specify the keystore password.

Specifying an authentication modeThe Probe for Microsoft EWS supports Basic and OAuth authentication.

Note : Basic authentication can be used to connect to Exchange Server and Exchange Online. From Q42020 onwards, OAuth authentication is the preferred method to connect to Exchange Online as Basicauthentication will be disabled.

Connecting using Basic authenticationTo connect using Basic authentication mode, configure the following probe properties:

• ServiceURL

The URL for the Exchange Server or Exchange Online service. For example:

ServiceURL : 'https://outlook.office365.com/EWS/Exchange.asmx'

If ServiceURL is not specified, the probe will perform AutoDiscovery to detect the service URL(Exchange Online only).

• Username

The email address of the user whose mailbox will be accessed by the probe. For example:

Username : '[email protected]'

• Password

The password of the user whose mailbox will be accessed by the probe. For example:

Password : 'password'

• TrustStore

Chapter 1. Probe for Microsoft EWS 3

The full path to the truststore used for TLS authentication (Exchange Server only). For example:

TrustStore : '/home/netcool/truststore.jks'

• TrustStorePassword

The password to access the truststore used for TLS authentication (Exchange Server only). For example:

TrustStorePassword : 'password'

• AuthenticationType

Set this property to Basic:

AuthenticationType : 'Basic'

Connecting using OAuth authenticationTo connect using OAuth authentication mode, use the following steps:

1. Configure Azure Active Directory:

a. Login to Azure Active Directory at https://aad.portal.azure.com/ with the user accountthat is used for the probe. This user account must have the Global Administrator role for theTenant. To determine the Tenant ID, go to Manage>Properties and copy the value for the TenantID.

b. Select Azure Active Directory in the left-hand navigation, then select App registrations underManage.

c. Select New registration. On the Register an application page, set the values as follows:

Set Name to a user-friendly name for your app.

Set Supported account types to the choice applicable to your scenario.

For Redirect URI, change the drop-down to Public client (mobile & desktop) and set the value tourn:ietf:wg:oauth:2.0:oob

d. Choose Register. On the next page, copy the value of the Application (client) ID and save it, youwill need it later.

e. Select API permissions in the left-hand navigation under Manage.f. Select Add a permission. On the Request API permissions page, select Exchange under

Supported legacy APIs.g. Select Application Permissions and then select full_access_as_app. Click on Add permissions.h. Select Grant admin consent for org and accept the consent dialog.i. Select Certificates & Secrets in the left-hand navigation under Manage.j. To create a new Client Secret, select New client secret, enter a short description and select Add.

Copy the value of the newly added Client Secret and save it.k. To create a new Client Certificate, upload the certificate containing the public key of the probe

server in either cer, pem or crt format.2. Configure the following properties for the probe:

• ServiceURL

The URL for the Exchange Server or Exchange Online service. For example:

ServiceURL : 'https://outlook.office365.com/EWS/Exchange.asmx'

If ServiceURL is not specified, the probe will perform AutoDiscovery to detect the service URL(Exchange Online only).

• Username


The email address of the user whose mailbox will be accessed by the probe. For example:

Username : '[email protected]'

• Password

The password of the user whose mailbox will be accessed by the probe. For example:

Password : 'password'

• AuthenticationType

Set this property to OAuth2:

AuthenticationType : 'OAuth2'

• Authority

URL of the authority that will authenticate the probe to connect with Exchange Online. This is in theformat: https://login.microsoftonline.com/<Tenant Domain or Tenant Id>. Forexample:

Authority : ‘https://login.microsoftonline.com/ewsprobe.microsoft.com'

The Tenant Id can be obtained from the Azure Active Directory Admin Center by navigating to theProperties section of the Dashboard of the Tenant.

• Scope

The scope of the authentication request. This is normally set to:

Scope : 'https://outlook.office.com/.default'

• ClientId

The Application (client) ID of the application registered in Azure Active Directory that representsthe probe. For example:

ClientId : '12345678-90ab-cdef-1234-567890abcdef'

• ClientSecret

The secret string used by the probe to authenticate with Azure when requesting a token. If notspecified, the probe will use ClientCertificate to authenticate. For example:

ClientSecret : 'abcdefghijklmnopqrstuvwxyz0123456789'

Note : For OAuth2 Authentication, you must use either ClientCertification or ClientSecret,but not both. If both are specified, the probe will use the ClientSecret.

• ClientCertificate

A keystore in the PKCS12 format that stores the probe server certificates (private and public keys).The public key in this keystore is the same as the one that was uploaded to Azure Active Directoryearlier. For example:

ClientCertificate : '/home/netcool/keystore.p12'

Note : You will need to perform the following steps:

a. Create a private key that will be used by probe properties:

/opt/IBM/tivoli/netcool/platform/linux2x86/jre64_1.8.0/jre/bin/keytool -genkey -alias win2019 -storetype PKCS12 -keyalg RSA -keystore keystore.p12

b. Convert the private key to crt type to be used by Office 365:


openssl pkcs12 -in keystore.p12 -clcerts -nokeys -out keystore.crt

• ClientCertificatePassword

The password to access the PKCS12 keystore. For example:

ClientCertificatePassword : 'password’

The probe will authenticate using either Client Secret or Client Certificate. By default, the probe will usethe Client Secret. To use the ClientCertificate, leave the ClientSecret property empty.

Compensating for Load BalancingWhen a monitored mailbox is shuffled onto a different server for load balancing purposes (especially inthe case of Exchange Online which is part of Office 365), this will cause the probe to lose connection toExchange Server/Online. To compensate for this, set the RetryCount property to a value greater than zeroto enable the probe to automatically restore the connection and continue monitoring the mailbox.

RetryCount : 3

Running the probeProbes can be run in a variety of ways. The way you chose depends on a number of factors, including youroperating system, your environment, and the any high availability considerations that you may have.

For details about how to run the probe, visit the following page on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/concept/running_probe.html

Data acquisitionEach probe uses a different method to acquire data. Which method the probe uses depends on the targetsystem from which it receives data.

The Probe for Microsoft EWS connects and subscribes to an Exchange Server or Exchange Online in orderto monitor for new incoming emails. The probe monitors the folder specified by the FolderNameproperty. The probe processes each email that satisfies the matching criteria specified by the Filterproperty to create Netcool/OMNIbus events that it forwards on to the ObjectServer.

Data acquisition is described in the following topics:

• “Filtering emails” on page 7• “Extracting plain text from the body of emails containing HTML” on page 8• “Deleting emails after processing” on page 9• “Event stream parsing as a single line” on page 9• “Line parsing with empty values” on page 10• “Event stream parsing for multiple lines” on page 10• “Line parsing with quotation marks” on page 12• “Line parsing with consecutive unquoted white spaces” on page 12• “Line parsing with consecutive unquoted white spaces” on page 12• “Formatting multi-line elements” on page 12• “Peer-to-peer failover functionality” on page 13• “Stream capture” on page 13




Filtering emailsThe Filter property allows you to specify a filter for the probe to use when selecting emails. Thisproperty allows you specify an expression that the probe uses for matching emails. The probe onlygenerates events for the emails that satisfy the matching the criteria, all other emails are ignored.

In the Filter property, you can specify an exact expression.

Note : The probe will not retrieve again those emails that have already been retrieved or filtered. To resetthe retrieval history and thus allow probe retrieve everything currently in mailbox again, you can manuallydelete the file specified by RecoveryFile property while probe is stopped and then restart the probe.

Specifying an expression for exact matching in one field onlyTo specify an expression for exact matching in one field only, use the following format:

field_name = "field value"

Example 1

To match the text "Alert from Splunk" within the Subject field of the email, specify the followingvalue in the ews.props file:

Filter : 'Subject = "Alert from Splunk"'

Example 2

To match the text "Alert from Splunk" in any of the fields of the email, specify the following value inthe ews.props file:

Filter : 'ANY = "Alert from Splunk"'

Specifying an expression for full matching with Java Regular Expression in one fieldonlyTo specify an expression full matching with Java Regular Expression in one field only, use the followingformat:

field_name LIKE "java_regex"

Example 1

To match the Subject field starting with the keyword #Netcool, specify the following value in theews.props file:

Filter : 'Subject LIKE "#Netcool.*"'

Example 2

To match a Netcool keyword in the email body, specify the following value in the ews.props file:

Filter : 'Body LIKE ".*Netcool.*"'

Example 3

To match either a Netcool or an Alert keyword starting the email body, specify the following value in theews.props file:

Filter : 'Body LIKE "(Netcool|Alert).*"'

Example 4

To match either a Netcool or an Alert keyword starting any email field, specify the following value in theews.props file:

Filter : 'ANY LIKE "(Netcool|Alert).*"'

Example 5

To match and process all emails, specify the following value in the ews.props file:


Filter : 'ANY LIKE ".*"'

Points to note about specifying matching criteriaCurrently the probe supports matching one field only.

Either a single quote (') or a double quote (") character is used to enclose a string literal or a Java regularexpression. Quotation marks are optional if the string literal contains no space.

LIKE (case-sensitive) is a special keyword that denotes the specified email field that is matched against aJava Regular Expression.

ANY (case-sensitive) is a special keyword that denotes any of the email fields. This means all fields will bescanned for fields that matches the specified criteria.

If the Filter property value is set to blank (empty string) it is equivalent to specifying the value 'ANYLIKE ".*"' which matches all emails.

The value of the Filter property is expected to be a one line specification. Any line terminator in theproperty value must be properly escaped with an additional backslash character (\). The correct value inthis property to denote a line terminator is either \\r, \\n, or \\r\\n which includes additional leadingbackslash to disable un-escaping before passing to probe parser.

A DEBUG level log message is produced when an email is discarded due to a filter evaluated to false.

The following is a list of the field names most commonly used within expressions:

• From• To• Date• Subject• Body

The following is a list of the field names that may also be used within expressions:

• Delivered-To• Received• Sender• Content-Type• Message-ID• Return-Path

Extracting plain text from the body of emails containing HTMLThe probe extracts plain text from the body of emails formatted in HTML.

During extraction, the probe performs the following steps:

1. Restores back to the original reserved characters all HTML character entities (for example, or<).

2. Removes and replaces all consecutive white spaces by a single space character (unless there is anyparagraph preserved by enclosing <pre></pre> tags). The resulting text appears in a tidier form.

Example

If the body of an email contains the following example HTML code:

<p>An <a href='http://example.com/'><b>example</b></a> link.</p><br>Below anempty line<div>Example text 1 distant text 2 and te<text color='red'></text>xt3</div>

The probe extracts the following plain text:


An example link. Below an empty line Example text 1 distant text 2 and text 3

Deleting emails after processingThe probe can permanently delete emails after processing.

For the purpose of automatic maintenance of the mailbox, in addition to normal deletion of emails bymoving them to a Deleted Items folder, the probe provides an option to permanently delete them fromthe mail store without moving them to the Deleted Items folder.

To enable this feature, set the PostProcessingAction property to HARD_DELETE.

Note :

In contrast to normal deletion, hard deletion is not recoverable by mailbox users. You should onlyconfigure this option if you are sure that there is no need to recover deleted emails in any case.

If you are using peer-to-peer processing, hard deletion is only performed by the probe instance that iscurrently the active master, but not the active slave. For more information about peer-to-peer processing,see “Peer-to-peer failover functionality” on page 13.

Event stream parsing as a single lineYou can configure the probe to parse the event stream as a single line with tokens separated by tokendelimiters.

Note : Whenever ParserSingleLines property is set to true, single-line event mode is switched onand then each line in email body is treated independently as single event. Therefore, theParserNextAlarmDelimiter, ParserAlarmStart and ParserAlarmEnd properties are no longerapplicable here because they are for delimiting events in multi-line event mode only. Whatever values setfor ParserNextAlarmDelimiter, ParserAlarmStart and ParserAlarmEnd will be ignored if youset ParserSingleLines to true, because the actual event delimiter will be always fixed to lineterminator.

To specify that the probe parses the event stream as a single line, set the ParserSingleLines propertyto true and specify the delimiter that separates tokens using the ParserElementDelimiter property.To specify name value-pair delimiters, use the ParserNVPDelimiter property.

For example, if ParserElementDelimiter property is set to |, and the probe receives the followingline:

"Hostname|PortNumber|Summary"

Then the probe parses the line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary"

For name value-pair example, if ParserElementDelimiter property is set to |,ParserNVPDelimiter property is set to =, and the probe receives the following line:

"Hostname=texth|PortNumber=1234|Summary=texts"

Then the probe parses the line into the following tokens:

Token1="Hostname=texth",Token2="PortNumber=1234",Token3="Summary=texts"NVP_Hostname=texthNVP_PortNumber=1234NVP_Summary=texts


Line parsing with empty valuesYou can also specify how the probe parses lines that contain empty fields (that is, adjacent delimiters withno data in between) using the ParserIgnoreEmptyFields property.

For example, the ParserSingleLines property is set to true, the ParserElementDelimiterproperty is set to |, and the probe receives the following line:

"Hostname|PortNumber|Summary|||Severity"

This line contains empty fields between Summary and Severity.

If the ParserIgnoreEmptyFields property is set to true, the probe ignores the empty fields and soparses the line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary",Token4="Severity"

If the ParserIgnoreEmptyFields property is set to false, the probe generates tokens with no valuesfor the empty fields and so parses the line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary",Token4="",Token5="", Token6="Severity"

Event stream parsing for multiple linesYou can configure the probe to parse multiple line events with multiple clients connections.

To set the probe to expect multiple line event streams, set the ParserSingleLines property to false.

The probe needs a mechanism to demarcate alarms. This is implemented in two ways: an eventterminator demarcates the events or a Java Regular Expression Pattern match is done for headers andfooters. For the former approach, the character specified by the ParserNextAlarmDelimiter propertyindicates the end of each event. The probe will use the latter approach only if both theParserAlarmStart and ParserAlarmEnd properties are set.

Example 1 - Start and End parsing with ParserParseAsLines set to true

In this example, set ParserAlarmStart to ALARM, ParserAlarmEnd to END, ParserSingleLines tofalse, and ParserParseAsLines to true. The probe receives the following line:

ALARMDATA1 ;DATA1a ;DATA1b ;DATA1B;DATA1 ;DATA1a ;DATA1b ;DATA1DD;END

The probe then parses the line into the following tokens:

Line1: DATA1 ;DATA1a ;DATA1b ;DATA1B;Line2: DATA1 ;DATA1a ;DATA1b ; DATA1DD;line_n: 2

Example 2 - Start and End parsing with delimiter

In this example, set ParserAlarmStart to ALARM, ParserAlarmEnd to END, ParserSingleLines tofalse, ParserParseAsLines to false, and ParserElementDelimiter to ;. The probe receives thefollowing line:

ALARMDATA1;DATA1a;DATA1b;DATA1c;DATA2;DATA2a;DATA2b;DATA2c;END



Token7: DATA2bToken8: DATA2cToken5: DATA2Token6: DATA2aToken3: DATA1bToken4: DATA1cToken1: DATA1Token2: DATA1aTokenCount: 12ALARM_START: ALARMALARM_END: END

Example 3 - Start and End parsing with Header property set

In this example, set ParserAlarmStart to EVENT FROM SYSTEM .*, ParserAlarmEnd to END OFEVENT, ParserAlarmHeader to Header.*, ParserSingleLines to false, ParserParseAsLinesto false, and ParserElementDelimiter to " " (whitespace). The probe receives the following line:

EVENT FROM SYSTEM XYZHEADER 1 HEADER2Value1a Value1bValue2a Value2bEND OF EVENT


ALARM_START: EVENT FROM SYSTEM XYZALARM_END: END OF EVENTALARM_HEADER: HEADER 1 HEADER2Token1: Value1aToken2: Value1bToken3: Value2aToken4: Value2b

Example 4 - Multi-line parsing using next alarm delimiter

In this example, set ParserNextAlarmDelimiter to ---, ParserSingleLines to false,ParserParseAsLines to false, and ParserElementDelimiter to ;. The probe receives thefollowing line:

ALARM1_LINE1_VALUE1;ALARM1_LINE1_VALUE2;ALARM1_LINE2_VALUE1;ALARM1_LINE2_VALUE2;ALARM1_LINE3_VALUE1;ALARM1_LINE3_VALUE2;---ALARM2_LINE1_VALUE1;ALARM2_LINE1_VALUE2;ALARM2_LINE2_VALUE1;ALARM2_LINE2_VALUE2;ALARM2_LINE3_VALUE1;ALARM2_LINE3_VALUE2;---

The probe then parses the line into the following tokens (for Alarm 1):

Token1: ALARM1_LINE1_VALUE1Token2: ALARM1_LINE1_VALUE2Token3: ALARM1_LINE2_VALUE1Token4: ALARM1_LINE2_VALUE2Token5: ALARM1_LINE3_VALUE1Token6: ALARM1_LINE3_VALUE2

The probe then parses the line into the following tokens (for Alarm 2):

Token1: ALARM2_LINE1_VALUE1Token2: ALARM2_LINE1_VALUE2Token3: ALARM2_LINE2_VALUE1Token4: ALARM2_LINE2_VALUE2Token5: ALARM2_LINE3_VALUE1Token6: ALARM2_LINE3_VALUE2


Line parsing with quotation marksIf a line contains single or double quotation marks (' or ", respectively), the probe can treat them aseither standard characters or special characters. If a line contains both single and double quotation theprobe treats the first quotation in that line as a special character only and treats the subsequent quotationas a standard character.

As standard characters, quotation marks have no significant meaning and are parsed as any othercharacter. As special characters, quotation marks indicate that the probe should treat characters fallingbetween them (including any spaces) as a single token. To specify that the probe treats quotation marksas special characters, set the ParserQuoteCharacter property to ". If no value is set for theParserQuoteCharacter property, then quote characters will be treated as normal characters.

For example, by default if the probe receives the following line:

"Example data one" "Example data two"

The probe parses the line into the following tokens:

Token1="Example data one" Token2="Example data two"

Line parsing with consecutive unquoted white spacesIf a line contains consecutive unquoted white spaces (that is, consecutive tabs or spaces in a line that donot fall within a pair of quotation marks), the probe can either maintain all the white spaces in the line orreduce the consecutive white spaces to a single space.

To specify that the probe maintains consecutive unquoted white spaces, set the ParserPreserveLineproperty to true. Otherwise, set the ParserPreserveLine property to false.

You can also specify that the probe strips certain characters from the event. To so, use theParserStripCharacter property to specify the character to strip from the event and you can use theParserReplaceStripCharWith property to specify a character to replace the strip character specifiedby the ParserStripCharacter property.

You can use the ParserTrimElement property to specify whether the probe strips leading and trailingwhite spaces and new lines from elements that it generates.

Formatting multi-line elementsYou can use the MultiLineFormat property to specify the format that the probe uses to build multi-lineelements.

The probe retrieves the full header and body of an email by building the multi-line elements $Header and$Body, using a printf function. The default value of the MultiLineFormat property is the line format%s_%d, where %s is the name of the element and %d is the line number. This produces elements such as$Header_1.

Note : To ensure that line elements are ordered correctly in the Event List details tab, use a left-0 padded,fixed-width line format to add zeros (0) at the beginning of values that are shorter than the width of theEvent List field. For example, the line format %s_%03d produces the following line elements:

• $Header_001• $Header_002• ...• $Header_nnn


Peer-to-peer failover functionalityThe probe supports failover configurations where two probes run simultaneously. One probe acts as themaster probe, sending events to the ObjectServer; the other acts as the slave probe on standby. If themaster probe fails, the slave probe activates.

While the slave probe receives heartbeats from the master probe, it does not forward events to theObjectServer. If the master probe shuts down, the slave probe stops receiving heartbeats from the masterand any events it receives thereafter are forwarded to the ObjectServer on behalf of the master probe.When the master probe is running again, the slave probe continues to receive events, but no longer sendsthem to the ObjectServer.

Example property file settings for peer-to-peer failover

You set the peer-to-peer failover mode in the properties files of the master and slave probes. The settingsdiffer for a master probe and slave probe.

Note : In the examples, make sure to use the full path for the property value. In other words replace$OMNIHOME with the full path. For example: /opt/IBM/tivoli/netcool.

The following example shows the peer-to-peer settings from the properties file of a master probe:

Server : "NCOMS" RulesFile : "master_rules_file"MessageLog : "master_log_file"PeerHost : "slave_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "master"PidFile : "master_pid_file"

The following example shows the peer-to-peer settings from the properties file of the corresponding slaveprobe:

Server : "NCOMS" RulesFile : "slave_rules_file"MessageLog : "slave_log_file"PeerHost : "master_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "slave"PidFile : "slave_pid_file"

Stream captureThe probe can capture all the EWS messages it receives in a stream capture file for debugging.

To enable stream capture, set the StreamCaptureFile property to the path of the file to which theprobe will write the messages received.

Note : The data stream capture function generates a lot of data. When you no longer require data fordebugging, set the StreamCaptureFile property to "". This disables the stream capture function.

Properties and command line optionsYou use properties to specify how the probe interacts with the device. You can override the default valuesby using the properties file or the command line options.

The following table describes the properties and command line options specific to this probe. Forinformation about common properties and command line options, see the IBM Tivoli Netcool/OMNIbusProbe and Gateway Guide.


Table 4. Properties and command line options

Property name Command line option Description

Filter string -filter string Use this property to specify what emailsthe probe processes by defining amatching expression to match the emailfield content against a pattern. Emailsthat match the filtering expression willbe processed by probe, otherwise theywill be ignored.

The default is Subject LIKE\'#NETCOOL.*\' (which instructs theprobe to process all emails that have#NETCOOL in the Subject field).

Note : The probe will not retrieve againthose emails that have already beenretrieved or filtered. To reset theretrieval history and thus allow proberetrieve everything currently in mailboxagain, you can manually delete the filespecified by RecoveryFile propertywhile probe is stopped and then restartthe probe.

FolderName string -foldername string Use this property to specify the name ofthe Exchange folder from which theprobe retrieves emails.

If you want to change the currentlymonitored folder, you should stop theprobe before changing this propertyvalue so that the new folder can takeeffect on probe startup.

The default is Inbox.

Note : This property supports thespecification of a subfolder under aparent folder, for example:

Inbox\\All Mails From JohnSmith

KeyStore string -keystorefile string Use this property to specify the locationof the keystore file that contains theNetcool/OMNIbus probe SSL certificateand corresponding private key whichrepresents a user of the Exchangemailbox. This keystore should containonly one key entry.

The default is "".

Note : You only need to configure thisproperty if Exchange is speciallyconfigured to enable certificate-basedclient authentication.


Table 4. Properties and command line options (continued)


KeyStorePassword string -keystorepassword string Use this property to specify thepassword required to access thekeystore specified by the KeyStoreproperty.

The default is "".

KeyStoreType string -keystoretype string Use this property to specify the type ofthe keystore specified by KeyStoreproperty.

Available options are: JKS, PKCS12,and any other keystore type supportedby JRE.

The default is JKS.

MultiLineFormat string -multilineformat string Use this property to specify the formatof the element name that the probeuses to build multiline elements from$Header and $Body.

The default is %s_%d.

ParserAlarmEnd string -parseralarmend string Use this property to specify the regularexpression that indicates the footer ofan event.

The default is "".

Note : When the ParserAlarmStartand ParserAlarmEnd properties arespecified, then theParserNextAlarmDelimiterproperty is ignored.

ParserAlarmHeader string -parseralarmheader string Use this property to specify the alarmheader regular expression to beextracted. This property is used inconjunction with theParserAlarmStart andParserAlarmEnd properties.

The default is "".

ParserAlarmStart string -parseralarmstart string Use this property to specify the regularexpression that indicates the header ofan event.

The default is "".

Note : When the ParserAlarmStartand ParserAlarmEnd properties arespecified, then theParserNextAlarmDelimiterproperty is ignored.




ParserElementDelimiterstring

-parserelementdelimiterstring

Use this property to specify the Javaregular expression that indicates thedelimiter for individual token in a line.

The default is "" (blank) which disablestokenization and therefore whole line istreated as a token.

Note : You must use a Java regularexpression to specify a value for thisproperty. For example: [ |\\t] woulddelimit by either a space, pipecharacter, or a tab.

ParserIgnoreEmptyFields string

-parserignoreemptyfields string

Use this property to specify whether theprobe discards tokens that contain nocontent. This property takes thefollowing values:

false: The probe does not discardtokens that contain no content.

true: The probe discards tokens thatcontain no content.

The default is true.

Note : Discarded tokens are not visiblein the rules file.

ParserNVPDelimiter string -parsernvpdelimiterstring

Use this property to specify the stringthat indicates the delimiter thatseparates the token name from thetoken value in the name-value pairs ofan event attribute.

The default is =.

ParserNextAlarmDelimiter string

-parsernextalarmdelimiter string

Use this property to specify the stringthat indicates the end of an event.

The default is <EVENT_DELIMITER>.

Note : The probe ignores this propertywhen values are specified for theParserAlarmStart andParserAlarmEnd properties .




ParserParseAsLines string -parserparseaslinesstring

Use this property to specify whether theprobe parses all entries between thealarm start and the alarm end one lineat a time as individual elements.

The default is false.

Note : Use this property only if theParserAlarmStart andParserAlarmEnd properties arespecified.

ParserPreserveLinesstring

-parserpreservelinesstring

Use this property to specify whether theprobe should preserve the lines createdby consecutive unquoted white spaces(rather than reducing them to a singlespace).

The default is false (which instructsthe probe to reduce them to a singlespace).

ParserQuoteCharacterstring

-parserquotecharacterstring

Use this property to specify the quotecharacter in the event. If this property isnot set, the parser will treat quotecharacters as normal characters.

The default is """.

ParserReplaceStripCharWith string

-parserreplacestripcharwith string

Use this property to specify thecharacter to replace the strip characterset by the ParserStripCharacterproperty.

The default is .

ParserSingleLines string -parsersinglelines string Use this property to specify whether theprobe parses each line as a singleevent.


Note : When this property is set totrue, the following properties formultiple-line parsing are ignored:ParserNextAlarmDelimiter,ParserAlarmStart,ParserAlarmEnd andParserAlarmHeader.

ParserStripCharacterstring

-parserstripcharacterstring

Use this property to specify thecharacter to strip from the event.

The default is "".




ParserTrimElement string -parsertrimelement string Use this property to specify whether theprobe strips leading and trailing whitespaces and new lines from elementsthat it generates.

The default is true.

Password string -password string Use this property to specify thepassword for the probe mail accountspecified by Username property.

The default is "".

PostProcessingActionstring

-postprocessingactionstring

Use this property to specify the kind ofaction that the probe performs on anemail that is retrieved and processed byprobe. This property takes the followingvalues:

DELETE: The probe moves the email tothe Deleted Items folder.

HARD_DELETE: The probe deletes theemail from mail server.

RELOCATE: The probe moves the emailto the folder in mail box specified by theRelocationFolder property.

The default is "" (which instructs theprobe to take no action, which leavesthe email as it is on server).

Note : Regardless of how this propertyis configured, no action is taken onthose emails not matching theexpression specified by the Filterproperty.

RecoveryFile string -recoveryfile string Use this property to specify the locationof the path to the probe session datafile that preserves necessary data toallow the probe to recover from aprevious shutdown and to continuefrom the previous session with EWS.

The default is $OMNIHOME/var/ews.recovery.

ReloctionFolder string -reloctionfolder string When the PostProcessingActionproperty is set to RELOCATE, use thisproperty specify the destination folderfor emails moved after processing.

The default is "".




ServiceURL string -serviceurl string Use this property to specify the URLthat the probe uses to communicatewith Exchange Web Services (EWS).This URL on the Microsoft ExchangeClient Access Server represents theEWS endpoint that services yourmailbox.

The scheme in this URL (HTTP orHTTPS) dictates whether TLS is enabledin the establishment of the connection;for example, HTTPS enables TLS.

An example value for this property is:https://outlook.office365.com/EWS/Exchange.asmx

The default is "" which causes theprobe to consult the Autodiscoverservice during the connection processto determine the service URL.

The probe consults the Autodiscoverservice at one of the following expectedURLs:

1. https://<email_domain>/autodiscover/autodiscover.xml

2. https://autodiscover.<email_domain>/autodiscover/autodiscover.xml

3. http://autodiscover.<email_domain>/autodiscover/autodiscover.xml(typically for redirection)

For example, if the Username propertyis set [email protected], theprobe will try to access theAutodiscover service at https://autodiscover.my.company.com/autodiscover/autodiscover.xml.

If the Autodiscover server uses acertificate which is not issued by a well-known Certificate Authority (CA), thenits certificate must be imported into thestore specified by the TrustStoreproperty.




ServiceURL string(description continued)

-serviceurl string With the availability of the ExchangeAutodiscover server in a deployedenvironment, you should use autodiscovery configuration for betterresilience, because the service URL canchange if the mailbox is migrated toanother server in a large forest ofservers, or if administrators deploy newClient Access servers.

Note : By going through theAutodiscover process, theestablishment of the connection toExchange takes about 10 secondslonger.

StreamCaptureFile string -streamcapturefile string Use this property to specify the full pathof the destination log file wherecaptured EWS messages are stored.

The default is "", which disables thestream capture feature.

Note : Stream capture is enabled onlywhen there is a value specified for thisproperty. You should only using thisproperty for temporary troubleshootingpurposes because the stream capturefile generated is not rotated with filesize considerations during probeexecution, and it is always emptied atprobe startup.

TrustStore string -truststore string Use this property to specify a file name(with full path) of a truststore file thatcontains trusted certificates includingcertificates of Exchange server,Certificate Authority (CA), andcertificates of the Autodiscover server.

The default value is blank (emptystring) which means the probe usesJRE-bundled trust store typicallylocated at <java-home>/lib/security/cacerts in order to verifythe Exchange server certificate. Fortight control, you should use a customtruststore to limit on the certificatesthat probe can accept.

The default is "".




TrustStorePassword string -truststorepasswordstring

Use this property to specify thepassword required to access thetruststore file specified by theTrustStore property.

TrustStoreType string -truststoretype string Use this property to specify the type oftruststore specified by the TrustStoreproperty.

Available options are: JKS, PKCS12,and any other keystore type supportedby JRE.

The default is JKS.

Username string -username string Use this property to specify the emailaddress of a mail account created inExchange for the probe to retrieveemails.

Note : The probe expects that the SMTPdomain of this email address is thesame as the User Principal Name (UPN)suffix of the associated user for thismail account in Active Directory. If theyare different, you can consider addingan alternative UPN suffix of the samevalue as SMTP domain using the ActiveDirectory administrative tools.

The default is "".

AuthenticationType string -authenticationtypestring

Use this property to specify theauthentication type to be used. Thisproperty takes the following values:

Basic: Basic authentication

OAuth2: OAuth authentication

The default is Basic.




Authority string -authority string Use this property to specify the URL tothe authority that will authenticate theprobe to connect with Exchange Online.This is in the format:

https://login.microsoftonline.com/<Tenant Domain or Tenant Id>

The Tenant Id can be obtained fromthe Azure Active Directory AdminCenter by navigating to the Propertiessection of the dashboard of the tenant.This property applies to OAuthauthentication only.

The default is "".

Scope string -scope string Use this property to specify the scopeof the authentication request. Thisproperty applies to OAuthauthentication only.

The default is https://outlook.office.com/.default.

ClientId string -clientid string Use this property to specify theApplication (client) ID of the applicationregistered in Azure Active Directory thatrepresents the probe. This propertyapplies to OAuth authentication only.

The default is "".

ClientSecret string -clientsecret string Use this property to specify the secretstring used by the probe to authenticatewith Azure when requesting a token. Ifnot specified, the probe will useClientCertificate to authenticate.

The default is "".

ClientCertificate string -clientcertificate string Use this property to specify the full pathto the keystore in the PKCS12 formatthat stores the probe server certificates(private and public keys). The public keyin this keystore is the same as the onethat was uploaded to Azure ActiveDirectory earlier.

The default is "".




ClientCertificatePassword string

-clientcertificatepassword string

Use this property to specify thepassword to access the PKCS12keystore specified asClientCertificate.

The default is "".

Properties and command line options provided by the Java ProbeIntegration Library (probe-sdk-java) version 12.0

All probes can be configured by a combination of generic properties and properties specific to the probe.

The following table describes the properties and command line options that are provided by the JavaProbe Integration Library (probe-sdk-java) version 12.0.

Note : Some of the properties listed may not be applicable to your probe.

Table 5. Properties and command line options


DataBackupFile string -databackupfile string Use this property to specify the path tothe file that stores data between probesessions.

The default is "".

Note : Specify the path relative to$OMNIHOME/var.

HeartbeatInterval integer -heartbeatintervalinteger

Use this property to specify thefrequency (in seconds) with which theprobe checks the status of the hostserver.

The default is 1.

Inactivity integer -inactivity integer Use this property to specify the lengthof time (in seconds) that the probeallows the port to receive no incomingdata before disconnecting.

The default is 0 (which instructs theprobe to not disconnect during periodsof inactivity).




InactivityAction string -inactivityaction string Use this property to specify the actionthe probe takes when the inactivitytimeout is reached:

SHUTDOWN: The probe sends aProbeWatch message to notify the userand then shuts down.

CONTINUE: The probe sends aProbeWatch message to notify the user,but does not shut down.

The default is SHUTDOWN.

InitialResync string -initialresync string Use this property to specify whether theprobe performs resynchronization onstartup. This property takes thefollowing values:

false: The probe does not requestresynchronization on startup.

true: The probe requestsresynchronization on startup.

For most probes, the default value forthis property is false.

If you are running the JDBC Probe, thedefault value for the InitialResyncproperty is true. This is because theJDBC Probe only acquires data usingthe resynchronization process.

MaxEventQueueSize integer -maxeventqueuesizeinteger

Use this property to specify themaximum number of events that can bequeued between the non native processand the ObjectServer.

The default is 0.

Note : You can increase this number toincrease the event throughput when alarge number of events is generated.




ResyncInterval integer -resyncinterval integer Use this property to specify the interval(in seconds) at which the probe makessuccessive resynchronization requests.

For most probes, the default value forthis property is 0 (which instructs theprobe to not make successiveresynchronization requests).

If you are running the JDBC Probe, thedefault value for the ResyncIntervalproperty is 60. This is because theJDBC Probe only acquires data usingthe resynchronization process.

RetryCount integer -retrycount integer Use this property to specify how manytimes the probe attempts to retry aconnection before shutting down.

The default is 0 (which instructs theprobe to not retry the connection).

RetryInterval integer -retryinterval integer Use this property to specify the lengthof time (in seconds) that the probewaits between successive connectionattempts to the target system.

The default is 0 (which instructs theprobe to use an exponentiallyincreasing period between successiveconnection attempts, for example, theprobe will wait for 1 second, then 2seconds, then 4 seconds, and so forth).

RotateEndpoint string -rotateendpoint string Use this property to specify whether theprobe attempts to connect to anotherendpoint if the connection to the firstendpoint fails.

This property takes the followingvalues:

false: The probe does not attempt toconnect to another endpoint if theconnection to the first endpoint fails.

true: The probe attempts to connect toanother endpoint if the connection tothe first endpoint fails.



ElementsThe probe breaks event data down into tokens and parses them into elements. Elements are used toassign values to ObjectServer fields; the field values contain the event details in a form that theObjectServer understands.

The following tables describe the elements that the Probe for Microsoft EWS generates for all emails thatit receives.

Table 6. Elements

Element name Element description

$AlarmCount This element indicates the total number of events inthe email body.

Note : The probe generates elements for each of theevents in the email body.

$AlarmIndex This element contains numeric index of this currentevent among all events in the enclosing email,starting from 1.

$BccRecipients This element contains the Bcc recipients of the email.They appear in the following format:

name1 <address1>; name2 <address2>; ...and so forth.

$Body This element contains the body of the email.

$Body_nn This element identifies a single line within the body ofthe email, where nn indicates the line number.

$Body_LineCount This element indicates the total number of lines in thebody of the email.

$CcRecipients This element contains the Cc recipients of the email.They appear in the following format:

name1 <address1>; name2 <address2>; ...and so forth.

$Date This element shows the date and time at which theemail was sent out by sender.

$DateCreated This element shows the date and time at which theemail was created in the Microsoft Exchange foldercurrently being monitored.

$DateReceived This element shows the date and time at which theemail was received by Microsoft Exchange.

$From This element indicates the sender of the email in theformat: name <email address>, for example:John Smith <[email protected]>.

Note : This is different from on-behalf sender.


Table 6. Elements (continued)


$FromAddress This element indicates the email address of thesender of the email.

$From Name This element indicates the name of the sender of theemail, for example: John Smith.

$Header This element contains the full header details of theemail.

$Header_nn This element identifies a single line within the headerof the email, where nn indicates the line number.

$Header_LineCount This indicates the total number of lines in the headerof the email.

$HeaderField_<field name> This element contains the content of the specifiedfield in email header.

$Importance This element indicates the importance of email as setby the sender.

$InternetMessageId This element contains the Internet message ID of theemail.

$IsRead This element indicates whether the email has beenread.

$ItemId This element contains the unique ID for the email inMicrosoft Exchange.

$ReplyTo This element contains the email addresses to whichreplies should be addressed. They appear in thefollowing format: name1 <address1>; name2<address2>; ... and so forth.

$SenderOnBehalf This element contains on-behalf sender of the email.If the email was not sent on behalf of another person,this element will be empty.

$Subject This element indicates the subject of the email.

$Severity This element indicates the severity level of the event.

Note : This element is available only when the emailbody contains a line in the format:Severity:<severity_value>.

$To This element indicates the email addresses of therecipients of the email.

This element has the following format: name1<address1>; name2 <address2>; and so forth.


Table 6. Elements (continued)


$Topic This element indicates the conversation topic ofrelated emails.

$Topic excludes conversation prefixes like Re orFwd. For example: If the email Subject is Re:Meeting Agenda, $Topic contains Meetingagenda.

The following tables describe the elements that the Probe for Microsoft EWS may generate for the eventswithin an email.

Table 7. Elements


$ALARM_START This element indicates the start of the current eventindexed by the $AlarmIndex element in the emailbody.

$ALARM_END This element indicates the end of the current eventindexed by the $AlarmIndex element in the emailbody.

$ALARM_HEADER This element contains the line the precede first lineactual tokens, after $ALARM_STARTin the currentevent indexed by the $AlarmIndex element in theemail body.

$line_n This element contains Total of lines in content of

the current event indexed by the $AlarmIndexelement in the email body.

$line<n> This element contains the nth line of content of thecurrent event indexed by the $AlarmIndex elementin the email body.

$NVP_<name of NVP> This element contains a named-value-pair (if oneexists) in the current event indexed by the$AlarmIndex element in the email body.

$TokenCount This element indicates the total number of tokens inthe current event indexed by the $AlarmIndexelement in the email body.

$Token<n> This element contains the nth token in the currentevent indexed by the $AlarmIndex element in theemail body.


Error messagesError messages provide information about problems that occur while running the probe. You can use theinformation that they contain to resolve such problems.

The following table describes the error messages specific to this probe. For information about genericerror messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

Table 8. Error messages

Error Description Action

Failed to initializeSSL context

SSL context for use of securesocket creation cannot beinitialized most likely due tomisconfiguration.

Check all SSL/TLS related probeproperties, key store and truststore properties.

Failed to load probeproperties

Failed to load and validateproperties configured in probeprops file.

Verify and ensure all probeproperties are properly specifiedin ews.props file.

Failed to initializeprobe recovery file

The recovery file specified inprobe configuration cannot beloaded or created.

Check whether appropriate filepermission has been granted, orotherwise remove the file for newcreation if it is corrupted.

Failed to query for newemails

Probe is unable to retrieve newemails from Microsoft Exchange.

Check that Microsoft Exchange isrunning correctly.

Failed to open Exchangefolder for emailreading

Probe is unable to bind to theExchange folder specified in probeconfiguration.

Check if the property is correctlyspecified.

Failed to load contentof new emails fromExchange

A query on the content of somenew emails from MicrosoftExchange did not succeed.

Check that you have specified theFilter property correctly.

Check that Microsoft Exchange isrunning correctly.

Failed to parse contentof a new email, emailis discarded

There is an error in retrieving andprocessing content of an email.

Refer to following exceptionmessage for more details.

User configured genericfeature of rotatingendpoint is notapplicable in thisprobe

The rotating endpoint has beenenabled by configuring theRotateEndpoint property.

This property not meant for thisprobe and should be configured tobe disabled.

Different folder ismonitored now comparedto last probe startup,sync history forprevious folder isdiscarded and lost

Sync history for previouslymonitored folder is discarded.

If probe change to monitorprevious folder again, it will startover and read all emails again.


Table 8. Error messages (continued)


Failed to contactAutodiscover service todetermine service URLfor email address

The probe failed to determine theservice URL for the specified emailaccount.

There are some possible reasonfor a failure to get the service URLfor specified email account:

1. Autodiscover service is notavailable for the domainspecified in user email address

2. Username is incorrect3. Account password is incorrect

Failed to connect toExchange at givenservice URL ofservice_URL

The probe failed to connect to theExchange Server Web Servicesinterface defined by the serviceURL.

Look at the HTTP/HTTPS URLstring at the end of the messageand verify that the URL denotes areachable network address fromthe machine on which the probe isinstalled, and verify thatUsername and Passwordproperties are specified correctly.

Failed to openrelocation folderspecified

The probe was unable to bind tothe relocation folder specified inprobe configuration.

Check that theReloctionFolder property iscorrectly specified.

Failed to subscribe toEWS for notification onnew email

There was an unexpected failureof a subscription, for which thereare with many possible reasons.

Inspect the log message thatimmediately follows this messageto determine the reason for thissubscription failure.




Filtered email withsubject of subject andID of email_id whichdoes not matchconfigured filter dueto filter

This message indicates that anemail has been filtered by theprobe and thus skipped forprocessing. Its subject, ID andreason for not matching the filtercriteria are included in the logmessage.

This log message is useful,especially when deploying theprobe for the first time, because ithelps you to identify why theprobe does not process aparticular email in the mailbox.

When deploying the probe for thefirst time, you should turn onDEBUG level messages by settingthe MessageLevel property todebug so that you can verifywhether you have set the Filterproperty properly and that theprobe is not filtering out any emailthat you want to keep.

Whenever an email is filtered outby probe, this message is logged.By looking at this log message,you can check whether an emailhas been filtered by probeunintentionally due to aninappropriate value set in theFilter property.

After verifying that the Filterproperty value has been setcorrectly, you should change thevalue of MessageLevel propertyto a value other than DEBUG.

Note : The probe will not retrieveagain those emails that havealready been retrieved or filtered.To reset the retrieval history andthus allow probe retrieveeverything currently in mailboxagain, you can manually delete thefile specified by RecoveryFileproperty while probe is stoppedand then restart the probe.

Unexpected error incurrent EWSsubscription,subscription is to bediscarded;ServiceResponseException: Unable to retrieveevents for thissubscription. Thesubscription must berecreated. The eventscouldn't be read.

The probe lost connection to theExchange server due to themonitored mailbox being shuffledonto a different server for loadbalancing.

Set RetryCount property in theews.props file to a value greaterthan zero so that the probe canautomatically restore theconnection after shuffling.




Failed to perform HTMLto plain textconversion on body of aHTML email with subjectsubject_name to plaintext version, emailbody content remainsintact.

The parser could not automaticallyconvert the HTML content in theemail body.

If the HTML content in the email isa correctly formatted, contact IBMsupport.

Failed to initializestream capture file.

The stream capture file specifiedin probe configuration cannot becreated or emptied.

Check whether the filepermissions on theStreamCaptureFile have beengranted correctly. Alternatively,remove the file manually thusforcing the probe to create a newfile.

AADSTS90002: Tenant'<tenant>' not found.This may happen ifthere are no activesubscriptions for thetenant. Check to makesure you have thecorrect tenant ID.Check with yoursubscriptionadministrator.

Incorrect Tenant domain name orTenant Id was specified for theAuthority.

The Authority should be specifiedin the format: https://login.microsoftonline.com/<Tenant domain name orTenant Id>.

Example using Tenant domainname:

https://login.microsoftonline.com/mybusiness.onmicrosoft.com

Example using Tenant Id:

https://login.microsoftonline.com/12345678-90ab-cdef-1234-567890abcdef-b8ea-4651-b810-e2884234d51d

AADSTS700027: Clientassertion contains aninvalid signature.[Reason - The key wasnot found., Thumbprintof key used by client:'ABCDEF1234567890ABCDEF1234567890ABCDEF12',

The certificate in the keystorespecified in ClientCertificatedoes not contain the thumbprint(SHA1 hash) of the certificateuploaded to Azure.

Ensure that the correct certificatefile was uploaded to Azure. Toview the certificate details, usethe following command:

keytool -v -printcert -file <file.crt>

Ensure that the correct keystore isspecified inClientCertificates. To viewthe certificate details, use thefollowing command:

keytool -list -v -keystore <keystore.p12>


Known issuesThis section explains known issues with this probe.

Probe does not show -version on AIX platformsThere is currently a known issue whereby the -version command does not return the probe's versiondetails correctly when running on AIX platforms. The probe's version can be seen in the probe's log.


Appendix A. Notices and TrademarksThis appendix contains the following sections:

• Notices• Trademarks

NoticesThis information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply that onlythat IBM product, program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be used instead. However, it is theuser's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.

Licensees of this program who want to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation Software Interoperability Coordinator, Department 49XA

© Copyright IBM Corp. 2016, 2020 35

3605 Highway 52 N Rochester, MN 55901 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.

The licensed program described in this information and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, orany equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimatedthrough extrapolation. Actual results may vary. Users of this document should verify the applicable datafor their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©Copyright IBM Corp. _enter the year or years_. All rights reserved.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

TrademarksIBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks of International BusinessMachines Corporation in the United States, other countries, or both.

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based trademarks are eitherregistered trademarks or trademarks of Adobe Systems Incorporated in the United States, othercountries, or both.


Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States,other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

Java™ and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States,other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Appendix A. Notices and Trademarks 37

IBM®

SC27-8743-02

ibm tivoli netcool/omnibus probe for microsoft exchange

Documents