Configuring the BMC Remedyforce monitor adapter

You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the BMC Remedyforce application.

The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the XML sample into the UI when configuring an adapter. 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 using XML only. However, after you switch to the XML view, and save the configuration in the XML from that view, you cannot use the form view for modifying that configuration.

To configure the monitor adapter:

Log on to the TrueSight Orchestration Grid Manager.
To access the adapters page, click the Manage tab, and then click the Adapters tab.
In the Adapters in Repository, select the bmc-ao-adapter-remedyforce-monitor check box.
Click Add to Grid to include the adapter in the Adapters on Grid list.
Click Configure corresponding to the newly added adapter.
On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or skip to step 7 to configure the adapter using the XML view:
1. Enter a name for the adapter.
  Note
  
  The Name field does not support single-quote (') and ampersand (&) characters.
2. Enter a description for the adapter.
3. Under Properties, enter or select values for the configuration elements.
  
  Include all required elements, indicated with an asterisk (*).
(optional) Configure the adapter in the XML view using the following substeps:
1. Enter a name and a description for the adapter.
2. Click Switch to XML View.
3. On the Warning message that appears, click Switch View.
4. Copy the configuration elements and attributes from the XML sample into the Properties text box, and then click OK.
  Note
  
  If the default value for an optional element is acceptable, omit the element. Do not include empty elements.
5. On the Warning message that appears, click Save.
  
  This action saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list.

The following table describes the node elements required for configuring the monitor adapter:

Node elements required to configure the monitor adapter

UI label	Element	Description	Required
Target	`<target>`	Specifies the host name or the IP address of the POP3 or IMAP mail server Example: imap.gmail.com	Yes
Port	`<port>`	Specifies the port on which the POP3 or IMAP server listens for events Default value: 110	No
User Name	`<user-name>`	Specifies the user name for the account to be monitored	Yes
Password	`<password>`	Specifies the password that corresponds to the `<user-name>` The `<password>` element can contain an `encryption-type` attribute.	Yes
Encryption Type	`encryption-type`	Indicates whether the password specified is encrypted Valid values: Base64, Plain (default)	No
Javamail Debug	`<javamail-debug>`	Specifies whether to turn on the debug message logging for JavaMail Valid values: true, false (default)	No
Email Address	`<email-address>`	Specifies the email-address of the account to be monitored BMC recommends that you do not configure multiple POP mail monitor adapters to monitor the same email-address.	Yes
Protocol	`<protocol>`	Specifies the email protocol to be used Valid values: pop3 (default), imap	Yes
Refresh	`<refresh>`	Specifies the interval, in seconds, to check for new messages Default value: 300 seconds (5 minutes)	No
Mail Timeout	`<mail-timeout>`	Specifies the time, in seconds, to maintain an established connection Default value: 60 seconds (1 minute)	No
Connection Timeout	`<connection-timeout>`	Specifies the time, in seconds, after which the session expires Default value: 30 seconds	No
Process all unread mails	`<process-all-unread-mails>`	Specifies whether to read the unread messages Note This element is valid only if you use the IMAP mail server. Valid values: true, false (default)	No
Disable Auth Login	`<disable-auth-login>`	Prevents the use of non-standard `AUTHENTICATE LOGIN` command with the POP servers Valid values: true, false (default)	No
Disable Auth Plain	`<disable-auth-plain>`	Prevents the use of `AUTHENTICATE PLAIN` command with the POP servers Valid values: true, false (default)	No
Delete After Read	`<delete-after-read>`	Determines whether a message must be deleted from the server after it is read by the adapter You must not use the `<delete-after-read>` element if you configure multiple POP mail monitor adapters to monitor the same email address. Exceptions are generated in the grid.log file and messages might be deleted before all the adapters read the message. Note This element is valid only if you use the POP mail server. Valid values: true, false (default)	Conditional; required to use the `<max-messages-per-connection>` element
Max Messages Per Connection	`<max-messages-per-connection>`	Specifies the maximum number of messages to be pulled per connection attempt If there are more messages on the server than the number specified, they are retrieved during the next polling. Use the `<max-messages-per-connection>` element only when the value of the `<delete-after-read>` element is true. Note This element is valid only if you use the POP mail server. Default value: 20	No
Ignore Attachments	`<ignore-attachments>`	Indicates whether the attachments must be ignored and excluded from the adapter event Valid values: true, false (default) (attachments permitted)	No
Create Subdirectory	`<create-subdirectory>`	Indicates whether each attachment must be downloaded into a separate directory Valid values: true, false (default) (download all the attachments into a single directory) Subdirectory name format: *attachment-download-directory/* <email-address>/message ID/ timestamp of download in epoch time{_} Sample subdirectory value: /mail/downloads/user@company.com/ Message1/1196967357	No
Attachment Download Directory	`<attachment-download-directory>`	Specifies the path and the directory where the attachments on the monitored email messages are downloaded This directory must exist on each peer on which the adapter is enabled. If this directory is not available, the configuration is considered invalid, and the adapter is not enabled. Default value: Java temp directory	No
Attachment Overwrite Existing	`<attachment-overwrite-existing>`	Indicates whether an attachment with the same file name has already been downloaded and overwrites that file with the current attachment If the value of the `<create-subdirectory>` element is true, the attachments are downloaded, ignoring the `<attachment-overwrite-existing>` element. Valid values: true, false (default) (preserves the original file)	No
Attachment Ttl	`<attachment-ttl>`	Specifies the period for which an attachment is permitted to reside in the download directory before being deleted You can specify a numeric value followed by a time designator Valid values for time designators: m - minutes h - hours d - days Default value: 10d	No
Max Attachment Size	`<max-attachment-size>`	Specifies the maximum file size, in MB, which can be attached to a mail message The maximum file size is defined per attachment; the total value of all the files can be greater, provided each file is less than or equal to the default value. Default value: 10 MB	No
Max Pool Threads	`<max-pool-threads>`	Specifies the maximum number of threads that can be used to download the attachments simultaneously Default value: 1	No
Delete Attachments On Exit	`<delete-attachments-on-exit>`	Deletes 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 after which the attachments that have exceeded the `<attachment-ttl>` period must be deleted You can specify a numeric value followed by a time designator. Valid values for time designators: m - minutes h - hours d - days Default value: 10m	No
File Name Filter	`<file-name-filter>`	Contains the elements that specify the file name criteria for downloading a file You can download only those files that satisfy the filter criteria.	Conditional; required if the `<file-name>` element is present
File Type Filter	`<file-type-filter>`	Contains the elements that specify the file type criteria for downloading an attachment You can download only those files that satisfy the filter criteria.	Conditional; required if the `<file-type>` element is present
Use Ssl Certificate	`<use-ssl-certificate>`	Specifies whether SSL certificates are used for authentication Valid values: true, false (default) Note Set this element to true if you want to establish a secure connection with the specified target.	No
Allow Unsigned Certificate	`<allow-unsigned-certificate>`	Specifies whether unsigned certificates are permitted for SSL authentication Note You do not need this element if the `<use-ssl-certificate>` element is false or blank. Set the value of this element to true if you are using self-signed SSL certificates (a common practice). On ecommerce sites or military installations, if you need to use signed certificates such as Verisign or Thawte, set the value of this element to false (a rare practice). Valid values: true, false (default)	No
Install Certificate	`<install-certificate>`	Updates the default keystore file, java.Home\jre\lib\security\cacerts with the certificates sent by the target URL during the SSLHandshake If the certificate is not verified, it is not installed. To install certificates successfully, the user who installs the peer that executes the request must have read or write access on the keystore file. Certificates are uninstalled when the adapter is disabled on a peer. If a TrueSight Orchestration peer is uninstalled without disabling this adapter, any certificates installed by the adapter continue to exist. The validity of installed certificates is verified once every 24 hours. The first verification is conducted 24 hours after the adapter is enabled. Note You do not need this element if the `<use-ssl-certificate>` is false or blank. Set the value of this element to true if you prefer to have security certificates installed automatically (a common practice). Set the value of this element to false, if you prefer to manually export the security certificate from the specified target server and manually import it into the TrueSight Orchestration's local peer's cacerts file (a rare practice). Valid values: true, false (default)	No
Passphrase	`<passphrase>`	Specifies the password to the keystore file (cacerts) local to the TrueSight Orchestration peer Note You do not need this element, if the `<use-ssl-certificate>` is false or blank. This value must match the passphrase in the keystore. You can change the passphrase using a keytool. If you make a change, you must update this value to reflect the new passphrase. Default value: changeit	No
Expand Plaintext Attachment	`<expand-plaintext-attachment>`	Specifies whether the plain text content of a message that is sent as an attachment appears in the `<bodypart>` element in an adapter event Valid values: true, false (default) If the value of `<expand-plaintext-attachment>` element is set to true, the plain text content of the message appears inside the `<bodypart>` element in an adapter event. Otherwise, the plain text content of the message appears inside the `<attachment>` element in an adapter event.	No
Expand Htmltext Attachment	`<expand-htmltext-attachment>`	Specifies whether the HTML data content of a message that is sent as an attachment appears in an adapter event Valid values: true, false (default) If the value of the `<expand-htmltext-attachment>` element is set to true, the HTML data content of the message appears inside the `<bodypart>` element in an adapter event. Otherwise, the HTML data content of the message appears inside the `<attachment>` element in an adapter event.	No
Character Set	`<character-set>`	Specifies the supporting CharSet The character set includes identifiers describing a series of universal characters. If you do not provide the `<character-set>` element in the configuration, then the email message is parsed based on the CharSet returned in the Content-Type of the email.	No
None	`<preferred-bodypart-text-format>`	Specifies whether to return the bodypart in the email messages in either of the following formats: Plain (default) HTML Note: This element is not available in the Form View. You can add it by switching to the XML view.	No

The following figure shows an XML sample for configuring the monitor adapter:

XML sample for configuring the monitor adapter

<config>
  <target>pop.gmail.com</target>
  <port>995</port>
  <user-name>allen.brooke@gmail.com</user-name>
  <password encryption-type="Plain">hasini23</password>
  <javamail-debug>false</javamail-debug>
  <email-address>allen.brooke@gmail.com</email-address>
  <protocol>pop3</protocol>
  <refresh>30</refresh>
  <mail-timeout>60</mail-timeout>
  <connection-timeout>30</connection-timeout>
  <process-all-unread-mails>false</process-all-unread-mails>
  <disable-auth-login>false</disable-auth-login>
  <disable-auth-plain>false</disable-auth-plain>
  <ignore-attachments>false</ignore-attachments>
  <create-subdirectory>false</create-subdirectory>
  <attachment-overwrite-existing>false</attachment-overwrite-existing>
  <attachment-ttl>10d</attachment-ttl>
  <max-attachment-size>10</max-attachment-size>
  <max-pool-threads>1</max-pool-threads>
  <delete-attachments-on-exit>false</delete-attachments-on-exit>
  <disk-cleanup-interval>10m</disk-cleanup-interval>
  <use-ssl-certificate>true</use-ssl-certificate>
  <allow-unsigned-certificate>false</allow-unsigned-certificate>
  <install-certificate>true</install-certificate>
  <passphrase>changeit</passphrase>
  <expand-plaintext-attachment>false</expand-plaintext-attachment>
  <expand-htmltext-attachment>false</expand-htmltext-attachment>
  <ignore-peer-name-in-attachment>false</ignore-peer-name-in-attachment>
</config>
<config>

The following figure shows an XML sample with POP3 and SSL disabled:

XML sample with protocol POP3 and SSL disabled

<config>
  <target>imap.gmail.com</target>
  <port>993</port>
  <user-name>remedyforcemonitor </user-name>
  <password encryption-type="Plain">bmcTest@1</password>
  <javamail-debug>false</javamail-debug>
  <email-address>remedyforcemonitor @gmail.com</email-address>
  <protocol>imap</protocol>
  <refresh>300</refresh>
  <mail-timeout>60</mail-timeout>
  <connection-timeout>30</connection-timeout>
  <process-all-unread-mails>false</process-all-unread-mails>
  <disable-auth-login>false</disable-auth-login>
  <disable-auth-plain>false</disable-auth-plain>
  <ignore-attachments>false</ignore-attachments>
  <create-subdirectory>false</create-subdirectory>
  <attachment-overwrite-existing>false</attachment-overwrite-existing>
  <attachment-ttl>10d</attachment-ttl>
  <max-attachment-size>10</max-attachment-size>
  <max-pool-threads>1</max-pool-threads>
  <delete-attachments-on-exit>false</delete-attachments-on-exit>
  <disk-cleanup-interval>10m</disk-cleanup-interval>
  <use-ssl-certificate>true</use-ssl-certificate>
  <allow-unsigned-certificate>false</allow-unsigned-certificate>
  <install-certificate>true</install-certificate>
  <passphrase>changeit</passphrase>
  <expand-plaintext-attachment>false</expand-plaintext-attachment>
  <expand-htmltext-attachment>false</expand-htmltext-attachment>
  <ignore-peer-name-in-attachment>false</ignore-peer-name-in-attachment>
</config>

The following figure shows an XML sample with IMAP and SSL disabled:

XML sample with IMAP and SSL disabled

<config>
  <target>imap.gmail.com</target>
  <port>143</port>
  <user-name>remedyforcemonitor</user-name>
  <password encryption-type="Plain">bmcTest@1</password>
  <javamail-debug>false</javamail-debug>
  <email-address>remedyforcemonitor@gmail.com</email-address>
  <protocol>imap</protocol>
  <refresh>300</refresh>
  <mail-timeout>60</mail-timeout>
  <connection-timeout>30</connection-timeout>
  <process-all-unread-mails>false</process-all-unread-mails>
  <disable-auth-login>false</disable-auth-login>
  <disable-auth-plain>false</disable-auth-plain>
  <ignore-attachments>false</ignore-attachments>
  <create-subdirectory>false</create-subdirectory>
  <attachment-overwrite-existing>false</attachment-overwrite-existing>
  <attachment-ttl>10d</attachment-ttl>
  <max-attachment-size>10</max-attachment-size>
  <max-pool-threads>1</max-pool-threads>
  <delete-attachments-on-exit>false</delete-attachments-on-exit>
  <disk-cleanup-interval>10m</disk-cleanup-interval>
  <use-ssl-certificate>false</use-ssl-certificate>
  <allow-unsigned-certificate>false</allow-unsigned-certificate>
  <install-certificate>true</install-certificate>
  <passphrase>changeit</passphrase>
  <expand-plaintext-attachment>false</expand-plaintext-attachment>
  <expand-htmltext-attachment>false</expand-htmltext-attachment>
  <ignore-peer-name-in-attachment>false</ignore-peer-name-in-attachment>
</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 BMC Remedyforce monitor adapter

To configure the monitor adapter:

Enabling custom logging

Encrypting an element's contents

Comments