Configuring the IMAP mail adapter

The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled.

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

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

The following table describes the IMAP mail adapter configuration elements 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 IMAP mail adapter

UI label

Element

Description

Required

Target

<target>

Specifies the host name or the IP address of the IMAP 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 IMAP server listens

If not specified, the adapter uses the a default value.

If the value of the <use-ssl-certificate> element is false, the default value is 143. If the value of the <use-ssl-certificate> element is true, the default is 993.

No

User Name

<user-name>

Specifies the user name for the account to be monitored

Conditional; required when the email application requires authentication

Password

<password>

Specifies the password that corresponds to the <user-name> provided

The <password> element can contain an encryption-type attribute.

Conditional; required when the email application requires authentication

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

Yes

Protocol

<protocol>

Specifies the email protocol to be used

Valid value: imap

Yes

Refresh

<refresh>

Specifies the interval, in seconds, for checking 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

Process All Unread Emails

<process-all-unread-mails>

Specifies whether to read the unread messages that are received when the adapter is inactive

If this element is set to true, emails that are received when the adapter is inactive are read. Otherwise, the emails that are received are ignored and only those messages that are received after the adapter is active are read.

Valid values: true, false (default)

No

Disable Auth Login

<disable-auth-login>

Prevents the use of a nonstandard AUTHENTICATE LOGIN command with IMAP servers

Valid values: true, false (default)

No

Disable Auth Plain

<disable-auth-plain>

Prevents the use of the AUTHENTICATE PLAIN command with POP servers

Valid values: true, false (default)

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 this 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

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

Create Subdirectory

<create-subdirectory>

Indicates whether each message's attachment must be downloaded into a separate directory

Valid values: true, false (default; downloads 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

Default value: Tomcat temp directory (on the computer where the CDP is installed)

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, 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: Attachments reside for 10 days

No

Max Attachment Size

<max-attachment-size>

Specifies the maximum file size, in MB, that 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 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 downloading an attachment

You can use wildcard characters, * and ?, to define the file name filter. Only files that satisfy the filter criteria are downloaded. For details, see the <file-name> element.

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. A file that matches at least one file name filter is downloaded. If you do not provide 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. Each ? represents one character.
Examples:

  • Specify the value of <file-name> as *.jar to download all jar files.
  • Specify the value of <file-name> as abc.jar* to download all jar files starting with 'abc'.
  • Specify the value of <file-name> as *.* to download all files.
  • Specify the value of <file-name> as abcd.* or abcd* to download a file starting with 'abcd' and with any extension. However, if you set <file-type> to a specific extension, for example 'html', then files starting with 'abcd' and with extension 'html' are downloaded.

No

File Type Filter

<file-type-filter>

Contains the elements that specify the file type criteria for downloading a file attachment

Only files that satisfy the filter criteria are downloaded.

Conditional; required if the <file-type> element is present

File Type

<file-type>

Specifies the criteria for file download, 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 criteria, a file with any file type is downloaded.
Example: If you set <file-name> to 'abc.' and set <file-type> to 'html', the *abc.html file, if it exists, 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

To establish a secure connection with the specified target, set this element to true.

No

Allow Unsigned Certificate

<allow-unsigned-certificate>

Specifies whether unsigned certificates are permitted for SSL authentication

Note

If <use-ssl-certificate> is false or blank, you do not need this element.

If you are using self-signed SSL certificates (a common practice), set the value of this element to true.

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

If <use-ssl-certificate> is false or blank, you do not need this element.

If you prefer to have security certificates installed automatically (a common practice), set the value of this element to true. 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), set the value of this element to false.

Valid values: true, false (default)

No

Passphrase

<passphrase>

Specifies the password to the keystore file (cacerts) local to the BMC Atrium Orchestrator peer.

Note

If <use-ssl-certificate> is false or blank, you do not need this element.

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

Ignore Peer Name In Attachment

<ignore-peer-name-in-attachment>

Specifies whether to add or remove the peer name from an email event XML

Valid values: true, false (default)

Notes

  • The <ignore-peer-name-in-attachment> element is checked only if the <ignore-attachments> is set to false.
  • If you set <ignore-peer-name-in-attachment> to true, the <peer-name> element is not added in an email event XML (to avoid event de-duplication failure).
  • If you set <ignore-peer-name-in-attachment> to false, the <peer-name> element is added in an email event XML when <ignore-attachments> is false and the the email contains an attachment.

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

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

XML template one of the IMAP 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>imap</protocol>
  <refresh></refresh>
  <mail-timeout></mail-timeout>
  <connection-timeout></connection-timeout>
  <process-all-unread-mails></process-all-unread-mails>
  <disable-auth-login></disable-auth-login>
  <disable-auth-plain></disable-auth-plain>
  <ignore-attachments></ignore-attachments>
  <create-subdirectory></create-subdirectory>
  <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>
  <ignore-peer-name-in-attachment></ignore-peer-name-in-attachment>
  <expand-plaintext-attachment></expand-plaintext-attachment>
  <expand-htmltext-attachment></expand-htmltext-attachment>
  <preferred-bodypart-text-format>Plain</preferred-bodypart-text-format>
</config>


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

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

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

XML sample of the IMAP adapter configuration for a single target

<config>
    <target>imap.runbox.com</target>
    <port>993</port>
    <user-name>testname</user-name>
    <password encryption-type="Plain">test</password>
    <character-set>UTF-8</character-set>
    <javamail-debug>false</javamail-debug>
    <email-address>test@runbox.com</email-address>
    <protocol>imap</protocol>
    <refresh>10</refresh>
    <mail-timeout/>
    <connection-timeout>60</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>
    <delete-after-read>false</delete-after-read>
    <max-messages-per-connection>20000</max-messages-per-connection>
    <expand-plaintext-attachment>true</expand-plaintext-attachment>
    <expand-htmltext-attachment>true</expand-htmltext-attachment>
    <ignore-peer-name-in-attachment>true</ignore-peer-name-in-attachment >
    <ignore-peer-name-in-attachment>true</ignore-peer-name-in-attachment>
</config>

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

XML sample of the IMAP adapter configuration for multiple targets

<configs>
      <config name="config1">
            <target>secure.runbox.com</target>
            <port>993</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>imap</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>
            <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>
            <ignore-peer-name-in-attachment>false</ignore-peer-name-in-attachment>
      </config>
      <config name="config2">
            <target>imap.runbox.com</target>
            <port>143</port>
            <user-name>imap_test</user-name>
            <password>password</password>
            <javamail-debug>true</javamail-debug>
            <email-address>imap_test@runbox.com</email-address>
            <protocol>imap</protocol>
            <refresh>30</refresh>
            <mail-timeout>30</mail-timeout>
            <connection-timeout>60</connection-timeout>
            <disable-auth-login>true</disable-auth-login>
            <disable-auth-plain>true</disable-auth-plain>
            <ignore-attachments>false</ignore-attachments>
            <create-subdirectory>false</create-subdirectory>
            <attachment-download-directory>C:\Attachments\</attachment-download-directory>
            <attachment-overwrite-existing>true</attachment-overwrite-existing>
            <attachment-ttl>1d</attachment-ttl>
            <max-attachment-size>8</max-attachment-size>
            <max-pool-threads>1</max-pool-threads>
            <delete-attachments-on-exit>true</delete-attachments-on-exit>
            <disk-cleanup-interval>5m</disk-cleanup-interval>
            <file-name-filter>
                  <file-name>T*</file-name>
            </file-name-filter>
            <file-type-filter>
                  <file-type>html</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></passphrase>
            <ignore-peer-name-in-attachment>true</ignore-peer-name-in-attachment>
      </config>
</configs>

The following figure shows an XML sample of the IMAP adapter configuration with expand plain text or HTML settings.

XML sample of the IMAP adapter configuration with expand plain text or HTML settings

<config>
   <target>imap.runbox.com</target>
  <user-name>user1</user-name>
  <password encryption-type="Plain">1234</password>
  <refresh>20</refresh>
  <protocol>imap</protocol>
  <email-address>user1@runbox.com</email-address>
  <ignore-attachments>false</ignore-attachments>
  <expand-plaintext-attachment>true</expand-plaintext-attachment>
  <expand-htmltext-attachment>true</expand-htmltext-attachment>
  <attachment-download-directory>C:\download_directory</attachment-download-directory>
  <create-subdirectory>true</create-subdirectory>
</config>
Was this page helpful? Yes No Submitting... Thank you

Comments