Configuring the POP adapter

The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after enabling the adapter. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

Adapter type: ro-adapter-pop_vv.rr.nn

To configure the POP mail adapter, see Configuring base adapters.

The following table describes the adapter configuration elements for the POP mail adapter that you can specify by using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the "UI label" column.

Configuration node elements for the POP mail adapter

UI label	Element	Description	Required
Target	`<target>`	Specifies the host name or the IP address of the POP3 server Note You can specify an IPv6 address for the `<target>` element—for example, `<target>[fe80::5097:4c5e:2289:76dd]</target>`.	Yes
Port	`<port>`	Specifies the port on which the POP3 server listens If the value of the `<use-ssl-certificate>` element is false, the default value is 110. If the value of the < `use-ssl-certificate>` element is true, the default value is 995.	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; is an attribute of the `<password>` element, not an element itself Valid values: Base64, Plain (default)	No
Character Set	`<character-set>`	Specifies the supporting CharSet Also called character set, it includes identifiers describing a series of universal characters. If you do not provide the `<character-set>` element in the configuration, then the email will be parsed based on the CharSet returned in the Content-Type of the email.	No
Javamail Debug	`<javamail-debug>`	Indicates that debug message logging for JavaMail must be turned on 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 value: pop3	Yes
Refresh	`<refresh>`	Specifies the frequency, 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, to wait when establishing a connection Default value: 30 seconds	No
Disable Auth Login	`<disable-auth-login>`	Prevents the use of non-standard `AUTHENTICATE LOGIN` command with POP servers Valid values: true, false (default)	No
Disable Auth Plain	`<disable-auth-plain>`	Prevents the use of `AUTHENTICATE PLAIN` command with 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 Do not use this 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. 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. This element is used only when the value of the `<delete-after-read>` element is true. Default value: 20	No
Ignore Attachments	`<ignore-attachments>`	Indicates whether attachments must be ignored and excluded from the adapter event Valid values: true, false (default) (attachments permitted)	No
Expand Htmltext Attachment	`<expand-htmltext-attachment>`	Specifies whether the HTML data 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-htmltext-attachment>` element is set to true, the HTML data content of the message appears inside the `<bodypart>` element in an adapter event. Else, the HTML data content of the message appears inside the `<attachment>` element in an adapter event.	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. Else, the plain text content of the message appears inside the `<attachment>` element in an adapter event.	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 into which 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 absent, the configuration is considered invalid and the adapter is not enabled. Default value: Java temp directory	No
Attachment Overwrite Existing	`<attachment-overwrite-existing>`	Indicates if 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, 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 time an attachment is permitted to reside in the download directory before being deleted This value is specified as a numeric value followed by a time designator. Valid values for time designators: m - minutes, h - hours, d - days Default value: 10d (allows attachments to reside for 10 days)	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 to be used to download attachments in parallel 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) (preserves downloaded files)	No
Disk Cleanup Interval	`<disk-cleanup-interval>`	Specifies the interval at which the deletion of attachments that have exceeded the `<attachment-ttl>` period must occur This value is specified as a numeric value followed by a time designator. Valid values for time designators: m - minutes, h - hours, d - days Default value: 10m (initiates cleanup every 10 minutes)	No
File Name Filter	`<file-name-filter>`	Contains the elements that specify the file name criteria for a file download You can download only those files that satisfy the filter criteria.	Conditional; required if the `<file-name>` element is present
File Name	`<file-name>`	Specifies the criteria for an attached file to be downloaded, based on the file name You can define one or more file names. An attachment that matches at least one file name filter is downloaded. If you do not provide a criteria, a file with any file name is downloaded. You can use wildcard characters, * and ? to define the file name filter. With a *, the wild card portion of the file name can contain an unlimited number of characters. With a ?, there is a one-to-one relationship between the ? and the file name character.	No
File Type Filter	`<file-type-filter>`	Contains the elements that specify the file type criteria for downloading a file attachment You can download only those files that satisfy the filter criteria.	Conditional; required if the `<file-type>` element is present
File Type	`<file-type>`	Specifies the criteria for an attached file to be downloaded, based on the file type You can define one or more file types. A file that matches at least one file type filter is downloaded. If you do not provide a criteria, a file with any file type is downloaded. Valid values: DOC XLS XML PDF HTML EXE	No
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 `<use-ssl-certificate>` 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 verification of a certificate fails, the certificate is not installed. To install certificates successfully, the user who installs the peer that executes the request must have read or write access to the keystore file. Certificates are uninstalled when the adapter is disabled on a peer. If a BMC Atrium Orchestrator peer is uninstalled without disabling this adapter, any certificates installed by the adapter continue to exist. The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled. Note You do not need this element if <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 BMC Atrium Orchestrator'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 BMC Atrium Orchestrator peer. Note You do not need this element, if `<use-ssl-certificate>` is false or blank. This value must match the passphrase in the keystore. You can change the passphrase using keytool. If you make a change, you must update this value to reflect the new passphrase. Default value: changeit	No
Preferred Bodypart Text Format	`<preferred-bodypart-text-format>`	Specifies whether to return the bodypart in the email messages in either of the following formats: Plain (default) HTML	No

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 BMC Atrium Orchestrator Platform version 7.8 or later to use the custom logging feature. These parameters will be ignored in earlier versions of BMC Atrium Orchestrator Platform.

These parameters are available with supported adapter versions. See your adapter 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

The following figures show XML templates of the adapter configuration for the POP adapter for a single target.

XML template one of the POP adapter configuration for a single target

<config>
  <target></target>
  <port></port>
  <user-name></user-name>
  <password encryption-type=""></password>
  <character-set></character-set>
  <javamail-debug></javamail-debug>
  <email-address></email-address>
  <protocol>pop3</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>
  <create-subdirectory></create-subdirectory>
  <ignore-attachments></ignore-attachments>
  <attachment-download-directory></attachment-download-directory>
  <attachment-overwrite-existing></attachment-overwrite-existing>
  <attachment-ttl></attachment-ttl>
  <max-attachment-size></max-attachment-size>
  <max-pool-threads></max-pool-threads>
  <delete-attachments-on-exit></delete-attachments-on-exit>
  <disk-cleanup-interval></disk-cleanup-interval>
  <file-name-filter>
    <file-name></file-name>
  </file-name-filter>
  <file-type-filter>
    <file-type></file-type>
  </file-type-filter>
  <use-ssl-certificate></use-ssl-certificate>
  <allow-unsigned-certificate></allow-unsigned-certificate>
  <install-certificate></install-certificate>
  <passphrase></passphrase>
  <preferred-bodypart-text-format>plain</preferred-bodypart-text-format>
</config>

XML template two of the POP adapter configuration for a single target

<configs>
      <config>
      ..........................
      </config>
</configs>

The following figure shows an XML sample of the POP adapter configuration for a single target.

XML sample of the POP adapter configuration for a single target

<config>
    <target>pop.gawab.com</target>s
    <port>110</port>
    <user-name>testname</user-name>
    <password encryption-type="Plain">aa</password>
    <character-set>UTF-8</character-set>
    <javamail-debug>false</javamail-debug>
    <email-address>aa@gawab.com</email-address>
    <protocol>pop3</protocol>
    <refresh>10</refresh>
    <mail-timeout/>
    <connection-timeout>60</connection-timeout>
    <disable-auth-login>false</disable-auth-login>
    <disable-auth-plain>false</disable-auth-plain>
    <delete-after-read>false</delete-after-read>
    <max-messages-per-connection>20000</max-messages-per-connection>
</config>

The following figure shows an XML sample of the POP adapter configuration for multiple targets.

XML sample of the POP adapter configuration for multiple targets

<configs>
     <config name="config1">
            <target>secure.runbox.com</target>
            <port>995</port>
            <user-name>sample_name</user-name>
            <password>sample_password</password>
            <javamail-debug>false</javamail-debug>
            <email-address>sample_name@runbox.com</email-address>
            <protocol>pop3</protocol>
            <refresh>20</refresh>
            <mail-timeout>10</mail-timeout>
            <connection-timeout>30</connection-timeout>
            <disable-auth-login>false</disable-auth-login>
            <disable-auth-plain>false</disable-auth-plain>
            <delete-after-read>false</delete-after-read>
            <max-messages-per-connection>10</max-messages-per-connection>
            <ignore-attachments>false</ignore-attachments>
            <create-subdirectory>true</create-subdirectory>
            <attachment-download-directory>C:\\DownloadAttachments\</attachment-download-directory>
            <attachment-overwrite-existing>true</attachment-overwrite-existing>
            <attachment-ttl>1d</attachment-ttl>
            <max-attachment-size>5</max-attachment-size>
            <max-pool-threads>3</max-pool-threads>
            <delete-attachments-on-exit>false</delete-attachments-on-exit>
            <disk-cleanup-interval>10m</disk-cleanup-interval>
            <file-name-filter>
                  <file-name>a*</file-name>
            </file-name-filter>
            <file-type-filter>
                  <file-type>pdf</file-type>
            </file-type-filter>
            <use-ssl-certificate>true</use-ssl-certificate>
            <allow-unsigned-certificate>true</allow-unsigned-certificate>
            <install-certificate>false</install-certificate>
            <passphrase>changeit</passphrase>
      </config>
      <config name="config2">
            <target>pop.runbox.com</target>
            <port>110</port>
            <user-name>sample_name</user-name>
            <password>sample_password</password>
            <javamail-debug>false</javamail-debug>
            <email-address>sample_name@runbox.com</email-address>
            <protocol>pop3</protocol>
            <refresh>20</refresh>
            <mail-timeout>10</mail-timeout>
            <connection-timeout>30</connection-timeout>
            <disable-auth-login>false</disable-auth-login>
            <disable-auth-plain>false</disable-auth-plain>
            <delete-after-read>false</delete-after-read>
            <max-messages-per-connection>10</max-messages-per-connection>
            <ignore-attachments>false</ignore-attachments>
            <create-subdirectory>true</create-subdirectory>
            <attachment-download-directory>C:\\DownloadAttachments\</attachment-download-directory>
            <attachment-overwrite-existing>true</attachment-overwrite-existing>
            <attachment-ttl>1d</attachment-ttl>
            <max-attachment-size>5</max-attachment-size>
            <max-pool-threads>3</max-pool-threads>
            <delete-attachments-on-exit>false</delete-attachments-on-exit>
            <disk-cleanup-interval>10m</disk-cleanup-interval>
            <file-name-filter>
                  <file-name>a*</file-name>
            </file-name-filter>
            <file-type-filter>
                  <file-type>pdf</file-type>
            </file-type-filter>
            <use-ssl-certificate>false</use-ssl-certificate>
            <allow-unsigned-certificate>false</allow-unsigned-certificate>
            <install-certificate>false</install-certificate>
            <passphrase>changeit</passphrase>
      </config> 
</configs>

The following figure shows an XML sample of the POP adapter configuration with attachment download settings.

XML sample of the POP adapter configuration with attachment download settings

<config>
  <target>pop.runbox.com</target>
  <user-name>user1</user-name>
  <password encryption-type="Plain">1234</password>
  <refresh>20</refresh>
  <protocol>pop3</protocol>
  <email-address>user1@runbox.com</email-address>
  <ignore-attachments>false</ignore-attachments>
  <attachment-download-directory>${CDPMachineTempDir}
  </attachment-download-directory>
  <max-attachment-size>1</max-attachment-size>
</config>

Configuring the POP adapter

Enabling custom logging

Comments