Configuring the HP Service Manager monitor adapter

You configure an adapter in TrueSight Orchestration Grid Manager. The configuration provides information about how the adapter interacts with the HP Service Manager application. Though each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties.

The form view provides an easy-to-use interface for configuring adapters. The form view prevents errors that might occur when you copy the configuration XML from the adapter documentation into the UI during configuration. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes by using XML only. However, after you switch to the XML view and save the configuration in the XML form, you cannot thereafter use the form view for modifying the configuration. For details about the procedure to configure a monitor adapter, see the procedure in Configuring the HP Service Manager actor adapter.

The following table describes the configuration elements for the monitor adapter. You cannot use the form view to configure elements and attributes that do not have an entry in the UI label column.

Node elements for configuring the monitor adapter

UI label	Element	Description	Required
None	`<config>`	Contains elements required for configuring the monitor adapter	Yes
Target	`<target>`	Specifies the host name or an IP address of the POP3 server	Yes
Port	`<port>`	Specifies the port on which the POP3 server listens Default value: 110	No
User Name	`<user-name>`	Specifies the user name for the email account to be monitored For example, if the email account to be monitored is user.name@company.com", then the user name is _user.name.	Yes
Password	`<password>`	Specifies the password that corresponds to the specified user name The password element can contain an `encryption-type` attribute (the Encryption Type field on the form in the form view) that indicates whether the password specified is encrypted. Valid values for `encryption-type`: base64, plain (default)	Yes
Javamail Debug	`<javamail-debug>`	Indicates whether to use javamail debug message logging Valid values: true, false (default) If the `<javamail-debug>` element is not specified, the default value of false is used.	No
Email Address	`<email-address>`	Specifies the email address of the account to be monitored	Yes
Protocol	`<protocol>`	Specifies the email protocol to be used Valid value: pop3	Yes
Refresh	`<refresh>`	Specifies the interval, in seconds, between checks for new messages Valid value: Any integer Default value: 300 seconds	No
Mail Timeout	`<mail-timeout>`	Specifies the time, in seconds, to maintain an established connection Valid value: Any integer Default value: 60 seconds	No
Connection Timeout	`<connection-timeout>`	Specifies the time, in seconds, to wait when establishing a connection Valid value: Any integer Default value: 30 seconds	No
Disable Auth Login	`<disable-auth-login>`	Specifies whether to prevent the use of the nonstandard `AUTHENTICATE LOGIN` command with IMAP servers Valid values: true, false (default)	No
Disable Auth Plain	`<disable-auth-plain>`	Specifies whether to prevent the use of the `AUTHENTICATE PLAIN` command with IMAP servers Valid values: true, false (default)	No
Delete After Read	`<delete-after-read>`	Specifies whether a message should be deleted from the server after the adapter reads it Valid values: true, false (default)	Conditional; required if the `<max-messages-per-connection>` element is specified
Max Messages Per Connection	`<max-messages-per-connection>`	Specifies the maximum number of messages to be pulled for a connection attempt If there are more messages on the server than the value specified, the remaining messages are retrieved during the next polling. Valid value: Any integer Default value: 20 Note: The `<max-messages-per-connection>` element is used only when `<delete-after-read>` is true.	No
Ignore Attachments	`<ignore-attachments>`	Indicates whether to ignore attachments and exclude them from the adapter event Valid values: true, false (default)	No
Create Subdirectory	`<create-subdirectory>`	Indicates whether each attachment must be downloaded in a separate directory Valid values: true, false (default) Subdirectory name format: <attachment-download-directory>/<emailAddress>/<messageID>/<timeStampOfDownloadInEpochTime> For example: /mail/downloads/user@company.com/Message1/1196967357	No
Attachment Download Directory	`<attachment-download-directory>`	Specifies the path and directory where the attachments for the monitored email messages will be downloaded Note: This directory must exist on each peer on which the adapter is enabled. If this directory does not exist, the configuration is considered invalid, and the adapter is not enabled. If you do not specify the `<attachment-download-directory>` element, attachments are downloaded to the Java temp directory.	No
Attachment Overwrite Existing	`<attachment-overwrite-existing>`	Specifies whether to overwrite a downloaded attachment file with the new (current) attachment, if the file name is the same Valid values: true, false (default) Note: If `<create-subdirectory>` is true, attachments are downloaded, ignoring the value of the `<attachment-overwrite-existing>` element.	No
Attachment Ttl	`<attachment-ttl>`	Specifies the time for which an attachment is permitted to reside in the download directory, before being deleted The value is specified as a numeric value and time designator. If the `<attachment-ttl>` element is not specified, a default value of 10d is assigned to allow attachments to remain in the download directory for 10 days. Valid time designators: m: minutes h: hours d: days	No
Max Attachment Size	`<max-attachment-size>`	Specifies the maximum file size, in MB, that can be downloaded from a mail message The value for `<max-attachment-size>` is defined for each attachment. The total of all files can be a greater value, provided each file is less than or equal to the specified value. If the `<max-attachment-size>` element is not specified, a default value of 10 is assigned.	No
Max Pool Threads	`<max-pool-threads>`	Specifies the maximum number of threads to be used to download attachments in parallel If the `<max-pool-threads>` element is not specified, a default value of 1 is assigned.	No
Delete Attachments On Exit	`<delete-attachments-on-exit>`	Specifies whether to delete all downloaded attachments when the adapter is stopped or disabled Valid values: true, false (default)	No
Disk Cleanup Interval	`<disk-cleanup-interval>`	Specifies the interval between deletions of attachments that have exceeded the value of `<attachment-ttl>` The value is specified as a numeric value and as a time designator. If the `<disk-cleanup-interval>` element is not specified, a default value of 10m is assigned, initiating a cleanup every 10 minutes. Valid time designators: m: minutes h: hours d: days	No
None	`<file-name-filter>`	Contains one or more `<file-name>` elements Only those file names that satisfy the criteria specified for using the `<file-name>` element can be downloaded.	Conditional; required if a `<file-name>` element is specified
File Name Filter	`<file-name>`	Specifies the file name filter for the attachment files that can be downloaded You can define one or more file name filters by using the following wildcard characters: asterisk (*): Represents multiple characters question mark (?): Represents a single character If the `<file-name>` element is not specified, an attachment with any file name is downloaded.	No
None	`<file-type-filter>`	Contains one or more `<file-type>` elements Only the file types that are specified by using the `<file-type>` element can be downloaded.	Conditional; required if a `<file-type>` element is specified
File Type Filter	`<file-type>`	Specifies the file type of an attachment that can be downloaded You can specify multiple file types: doc, xls, XML, pdf, html, exe, and so on. If the `<file-type>` element is not specified, an attachment of any file type is downloaded.	No
Use Ssl Certificate	`<use-ssl-certificate>`	Specifies whether SSL certificates can be used for authentication Valid values: true, false (default)	No
Allow Unsigned Certificates	`<allow-unsigned-certificates>`	Specifies whether unsigned certificates are permitted for SSL authentication The `<allow-unsigned-certificates>` element is ignored if `<use-ssl-certificate>` is false. Valid values: true, false (default)	No
Install Certificate	`<install-certificate>`	Specifies whether to update the default keystore file (<java.home>\jre\lib\security\cacerts ) with the certificates sent by the target URL during the SSL handshake Valid values: true, false (default) To successfully install certificates, the user that installed the peer which executes the request must have read and write access to the keystore file. The `<install-certificate>` element is ignored if `<use-ssl-certificate>` is false. Certificates are uninstalled when the adapter is disabled on the peer. If you uninstall a BMC Run Book Automation peer without disabling the adapter, any certificates installed by the adapter will remain on the peer. If the verification of a certificate fails, the certificate is not installed.	No
Passphrase	`<passphrase>`	Specifies the passphrase for the keystore file to be used to install certificates The value for the `<passphrase>` element must match the passphrase in the keystore. The passphrase can be changed by using keytool. If a change is made, this value must be updated to reflect the new passphrase. The `<passphrase>` element is ignored if `<use-ssl-certificate>` is false. Default value: changeit	No

The following figures show XML templates for the monitor adapter configuration with a plain and an encrypted password.

XML template for configuring the monitor adapter with a plain password

<config>
  <target></target>
  <user-name></user-name>
  <password></password>
  <javamail-debug></javamail-debug>
  <email-address></email-address>
  <protocol></protocol>
  <refresh></refresh>
  <mail-timeout></mail-timeout>
  <connection-timeout></connection-timeout>
  <disable-auth-login></disable-auth-login>
  <disable-auth-plain></disable-auth-plain>
  <delete-after-read></delete-after-read>
  <max-messages-per-connection></max-messages-per-connection>
</config>

XML template for configuring the monitor adapter with an encrypted base64 password

<config>
  <target></target>
  <user-name></user-name>
  <password encryption-type="Base64"></password>
  <javamail-debug></javamail-debug>
  <email-address></email-address>
  <protocol></protocol>
  <refresh></refresh>
  <mail-timeout></mail-timeout>
  <connection-timeout></connection-timeout>
  <disable-auth-login></disable-auth-login>
  <disable-auth-plain></disable-auth-plain>
  <delete-after-read></delete-after-read>
  <max-messages-per-connection></max-messages-per-connection>
</config>

Enabling custom logging

To enable custom logging for the adapter, you must specify a log file name. You can also provide additional parameters for logging.

Note

You must be using TrueSight Orchestration version 8.1 or later to use the custom logging feature. These parameters will be ignored in earlier versions of TrueSight Orchestration Platform.

These parameters are available with supported adapter versions. See TrueSight Orchestration Content documentation for details.

Log File Name: Provide a name for the log file.
This file will be stored in the AO_HOME/tomcat/logs directory. If Log File Max Backup Index value is greater than 0, the log file name is suffixed with the backup index. For example, if the parameter value is a.log, backup log files will have names, such as a.log.1, a.log.2.
Log File Size: Specify a size limit for the log file.
If the value specified for Log File Max Backup Index is greater than 0, when the specified size is reached, the current file is renamed with the suffix .1. Otherwise, the log file will be reset and over-written. The default value is 10MB. The available units are KiloBytes (KB), MegaBytes (MB) or GigaBytes (GB).
Log File Max Backup Index: Enter the maximum number of backup files allowed. The default value is 10.
Log File Append: Select this option to append new log information to the existing information in the file. If unselected, the file will be overwritten with new log information.

Log Level: Enter the logging level using one of the following choices:

Logging level	Description
DEBUG	The most detailed logging level; logs low-level messages, normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
INFO (default)	Logs normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
WARN	Logs recoverable erroneous conditions and unrecoverable erroneous conditions
ERROR	The least detailed logging level; logs only error conditions that are not usually recoverable

Encrypting an element's contents

You can add the attribute secure="true" to an XML adapter element XML view to ensure that the element's contents is encrypted when displayed.

Note

You must be using TrueSight Orchestration Platform version 8.1 or later to use this encryption attribute.

Configuring the HP Service Manager monitor adapter

Enabling custom logging

Encrypting an element's contents

Comments