1. Overview
ResponseMaster uses a series of configuration files to control how it will process returned email messages. This document explains the meaning of each setting in each file. Example configuration files are supplied with the product to assist you with configuring ResponseMaster. The configuration files are all XML documents, but no experience with XML is required to configure the system. You can either edit the configuration files directly or use the ResponseMasterConfig program to edit them through a straightforward interface. ResponseMasterConfig does yet not have documentation, but ToolTips are available for every item in the interface.
In all configuration files, any file path parameters can use an absolute path or relative path. There are two different types of relative paths: (1) Use “.” for the application path… e.g. “./config/default.disposition.xml” (2) Use “+” for the path of the config file that contains the setting… e.g. “+/default.disposition.xml”. If the application is run from c:ResponseMaster with master.xml in c:ResponseMasterconfig, both of the examples above would point to c:ResponseMasterconfigdefault.disposition.xml
We recommend looking at the sample configuration files while reading this document. You can find them in the ResponseMasterconfig directory of your installation.
2. Master
The master configuration file (default name = “master.xml”) points to some global config files and lists the mailboxes that should be scanned.
2a. Monitor Config File
The MonitorConfigFile setting allows you to specify which file to read the monitoring settings from. In most cases, “monitoring” is simply logging to a text file. Please refer to Section 3 for more information of the contents of this file.
2b. Mailbox Parameters
Mailbox parameters define the mailbox(s) that will be monitored by ResponseMaster. ResponseMaster will attach to the mailbox(s) defined in this section of the master configuration file and process the email that is returned to them.
Name
This is the name that will be used to identify this mailbox in all reports and logs generated by ResponseMaster. This name does not need to be the same as the name of the mailbox on the mail server.
Protocol
The protocol to use to connect to the mail server.
Possible Values:
- imap – Use IMAP to connect to the mailbox.
- imaps – Use secure IMAP to connect to the mailbox.
- pop3 – Use POP3 to connect to the mailbox.
- pop3s – Use secure POP3 to connect to the mailbox.
- maildir – Read messages directly from a maildir-style folder structure.
- highperformancemaildir – Like maildir, but writes to disk less frequently, so it performs better. However, it is less reliable since it holds info in memory longer without writing it to disk.
- Default=”imap”
- Optional.
Host
The network name or IP address of the mail server that hosts the mailbox to be monitored.
Required if the Protocol is imap, imaps, pop3, or pop3s, ignored otherwise.
Port
The TCP/IP port to connect to the mailserver on. Use “-1″ for the default port for the service (143 for imap, 993 for imaps, 110 for pop, 992 for pops).
Default=”-1″
Optional.
User
The username and alias used to connect to the mailbox.
For Microsoft Exchange, this takes the form
NTDomainNTusernamemailAlias
On most systems, the NTusername and mailAlias are the same, but they do not need to be.
For most other mail servers, it is simply a username.
Required if the Protocol is imap, imaps, pop3, or pop3s, ignored otherwise.
Password
The password for the mailbox. For MS Exchange, this is the NT password of the user specified in the User setting. When you use ResponseMasterConfig to edit the configuration, this setting is encrypted in the configuration file. If you edit the file manually, you do not need to encrypt it.
Required if the Protocol is imap, imaps, pop3, or pop3s, ignored otherwise.
Subfolder
The subfolder of the inbox to process. Typically, this setting is omitted, and ResponseMaster processes the email in the Inbox. The subfolder setting is used almost exclusively for internal testing. We place the “test case” into a subfolder, and then ResponseMaster scans only that subfolder.
Note: if the subfolder value begins with a slash (“/”), then ResponseMaster processes a subfolder of the root folder instead of a subfolder of the Inbox. This can be useful, for example, for processing the Spam folder of an IMAP mailbox. Default= “”
Optional.
MailHomeFolder
The root folder of the maildir structure on the file system.
Required if the protocol is maildir or highperformancemaildir, ignored otherwise
LimitOnCurSize
Only relevant if the protocol is maildir or highperformancemaildir. The maximum number of messages in the “cur” folder.
Possible Values:
- <= 0 – Unlimited; all the messages are moved from new to cur
- >0 – The number of messages that should be in cur at the start of each cycle.
Default=-1
Optional. Ignored if protocol is not maildir or highperformancemaildir.
ExpungeWorkaround
For IMAP, if ExpungeWorkaround is set ResponseMaster will close and reopen the mailbox rather than just expunging it.
Set this to 1 if you are having trouble with ResponseMaster not finding new messages.
Possible Values:
- 0 – Use expunge.
- 1 – Close and reopen the mailbox each time.
Default=0
Optional.
MaxOpenTime
The maximum time (in seconds) to keep the mailbox open without closing it and reopening it.
If your mail server has a session timeout or you are having strange issues where mail isn’t being found, you can try adjusting this setting.
We have seen success with 3600 seconds for accessing Exchange servers via IMAP
Possible Values:
- <=0 – no time limit.
- >0 – The maximum time to keep the mailbox open (in seconds).
Default=-1
Optional.
Note: This setting is new in build 686.
MsgsPerThreadBeforeRefresh
The number of messages to process on each thread before expunging the messages from the mailbox and refreshing the connection. If your mailbox is typically large, and your connection is reliable, you may want to increase this value. Typically, this parameter can be omitted.
Default=50 messages per thread
Optional.
WaitTime
The amount of time a thread will pause after processing a message before looking for the next message to process (in milliseconds). This setting can be increased if the load that ResponseMaster places on the mail server is unacceptable. Typically, this parameter can be omitted.
Default=100 milliseconds
Optional.
ErrorWaitTime
The amount of time to pause if an error is encountered while retrieving or processing a message (in seconds). Typically, this parameter can be omitted.
Default=15 seconds
Optional.
NoMessagesWaitTime
The amount of time to pause if there are no messages in the mailbox (in seconds). If the inbox being monitored is extremely active, you may want to decrease this setting. Typically, this parameter can be omitted.
Default=60 seconds
Optional.
CloseImmediatelyIfEmpty
For POP (or if ExpungeWorkaround is set) ResponseMaster will close the mailbox immediately after processing the last message rather than after the NoMessagesWaitTime is complete.
Set this to 1 if you are having trouble with ResponseMaster not deleting messages when the mailbox is almost empty.
Possible Values:
- 0 – Close and reopen after NoMessagesWaitTime.
- 1 – Close and reopen just after processing the last message, before NoMessagesWaitTime.
Default=0
Optional.
New in build 671.
Threads
The number of concurrent processing threads to use for this mailbox. If the mail server is slow and/or the inbox is very active, or there is a large backlog of messages, you may want to increase this setting. Increasing this value to more than 5 threads is not recommended. Typically, 1 thread is sufficient.
Note: The Software License Agreement for ResponseMaster limits the number of threads that you are permitted to use.
Default=1
Optional.
CategorizationRulesFileName
The name(s) of the Categorization Rules configuration file(s) used for this mailbox. You should not change the name defined by default unless advised by Extreme Messaging Technical Support. If, for some reason, alternative categorization rules are required, please contact Extreme Messaging.
Default=+/categorization.xml
Required.
DispositionFileName
The name of the disposition configuration file to use for this mailbox. It is possible that you will need to modify this file. The instructions for modifying this file can be found in Section 4 of this document.
Default=+/default.disposition.xml
2c. Custom Item Definition Files
This is an advanced topic, please refer to the Advanced Topics guide for more information.
MessageFieldsFile
The name(s) of the configuration file(s) to read the message field list from.
You should use customMessageFields.xml to define your own message fields.Typically, there will be two entries, “+/customMessageFields.xml” and “+/systemMessageFields.xml”
Default=+/MessageFields.xml
Optional, but highly recommended.
CategoryDefinitionsFile
The name(s) of the configuration file(s) to read the category list from.
Typically, there will be two entries, “+/customCategoryDefinitions.xml” and “+/systemCategoryDefinitions.xml”
You should use customCategoryDefinitions.xml to define your own categories.
Default=+/categoryDefinitions.xml
Optional, but highly recommended.
DispositionTypesFile
The name(s) of the configuration file(s) to read the disposition list from.
Typically, there will be two entries, “+/customDispositionTypes.xml” and “+/systemDispositionTypes.xml”
You should use customDispositionTypes.xml to define your own disposition types.
Default=+/dispositionTypes.xml
Optional, but highly recommended.
2d. License File
The name of the configuration file to read the license information from.
This file is provided to you by Extreme Messaging. Please contact us if you need a new license file.
Default=+/license.xml
2e. Other
OnePass
If OnePass is set to 1, ResponseMaster exits after processing the messages in the mailbox once. It does not delete them.
Optional.Default=0We use this setting internally for regression testing. You may want to use it during your initial testing, but certainly won’t want to use it in production.
RetryIndefinitelyOnStartup
Normally, ResponseMaster will stop immediately upon startup if there are certain kinds of problems, for example, if it is unable to connect to the database specified in a WriteToDB disposition.
If this setting is set to 1, ResponseMaster will keep retrying indefinitely if it encounters an error during startup.
If ResponseMaster is often restarted while unattended, you may want to set this to 1. If you do, be sure to check the logs carefully after making any config changes to avoid non-stop errors.
Default=0
Optional.
Note: This setting was added in build 692.
3. Monitor Configuration File
The monitor configuration file defines the set of monitoring classes to call for each “event” that occurs.
The default name and location for the monitor configuration file is “+/monitor.xml”.
Some examples of “events” are:
- An error was raised
- A warning was raised
- A message was processed
For each event, for each monitoring item defined in this configuration file, the Monitoring Manager calls the appropriate function from the IMonitor interface (please refer to Advanced Topics for more information).
The monitor config file consists of a root Monitors element, with a child Monitor element for each monitoring item, and a JMX element. Each Monitor element contains a ClassName element that specifies a class that implements the IMonitor interface, and a Parameter element, which specifies the parameter to use to initialize the monitor.
Currently, there are three monitors provided with ResponseMaster.
The logger (ClassName=com.extrememessaging.ResponseMaster.monitor.CLogger) writes messages to a text file.
The reporting module (ClassName=com.extrememessaging.ResponseMaster.monitor.HistoricalCharts) creates a few simple graphs showing the categorization trends.
The email monitor (ClassName=com.extrememessaging.ResponseMaster.monitor.EmailMonitor, new in build 692) emails Error messages.
The Parameter for both in the name of the config file that they should read their settings from.
3a. Log Configuration File
The Log Configuration File specifies the settings that the logger should use.
It consists of a root LogConfig element with the following child elements:
LogFile
Controls which file the logging messages are written to.
Optional.Default=./output/logFile.txt
LogLevel
Controls which messages (by severity) are written to the log and which are suppressed.
Possible Values:
- Error – Only system messages and error messages are written to the log.
- Warning – Warning, error, and system messages are written to the log.
- Trace – All messages are written to the log.
Default=Warning
Optional.
LogToConsole
Controls whether or not logging messages are written to the application console interface.
Possible Values:
- 0 – Logging messages are not written to the console.
- 1 – Logging messages are written to the console.
Default=0
Optional.
LogBackupInterval
Controls when the log file is backed-up.
Possible Values:
- Never – No matter how long the application runs, only one log file is created.
- Daily – A new log file is created for each day.
- Hourly – A new log file is created for each hour.
- EveryTenMinutes – A new log file is created every 10 minutes (new in build 729).
Default=Daily
Optional.
Note: Before build 659, this setting was called “LogBackupDaily” and the possible values were 0 and 1, corresponding to “Never” and “Daily” respectively.
LogBackupFilesToKeep
Controls the number of log backup files to keep.
Only relevant if LogBackupInterval is not Never
Possible Values:
- 1 to 1000
Default=14
Optional.
Note: Before build 659, this setting was called “LogBackupDaysToKeep”.
FileEncoding
Which encoding should the log file be written in.
Note: if you switch this value, you should probably rename/delete the existing file.
Possible Values:
Any valid encoding in Java. Two likely choices are ASCII and UnicodeLittle
Default=ASCII
Optional.
Note: This setting is new in build 682.
3b. Reporting Configuration File
The Reporting Configuration File specifies the settings that the Historical Charts reporting module should use.
It consists of a root HistoricalCharts element with the following child elements:
OutputDirectory
Controls which directory the images and html are written to.
Optional.Default=./output/reports
DataDirectory
Controls which directory the data files are written to. The data files are used to preserve the historical data when ResponseMaster is restarted.
Default=./output/data
3c. Email Monitor Configuration File
The Email Monitor File specifies the settings for emailing error messages.
It consists of a root EmailMonitor element with the following child elements:
SMTPServer
The hostname or IP address of the SMTP server to send the errors through.
Optional.Default=localhost
SMTPPort
The IP port of the SMTP server to send the errors through.
Default=25
Optional.
SubjectFormat
The subject for the email. You can use %message% as a wildcard for the error message.
Default=Error from ResponseMaster
Optional.
Retries
The number of times to try sending the email.
Default=10
Optional.
From
The From address for the messages.
Required.
Addresses
A list of mail addresses (in “Address” nodes) that the mail will be forwarded to.
3d. JMX
The JMX section controls what information is exposed through Java Management Extensions (JMX).
Note: If you enable JMX, you will need to include jmxri.jar and jmxtools.jar in your classpath (see the Installation Guide for information about how to change the classpath). These jars, and more information about JMX, are available from Sun at http://java.sun.com/products/JavaManagement/.
It contains the following child elements:
JMXEnabled
Should JMX be enabled. If this setting is 0, all the rest of the settings are ignored
Optional.Default=0
ManageLoggerWithJMX
If this setting is enabled, you can change the logging level at runtime through JMX
Default=0
Optional.
MonitorMailboxesWithJMX
If this setting is 1, each mailbox will publish its status to JMX
Default=0
Optional.
MonitorMailboxThreadsWithJMX
If this setting is 1, each mailbox thread will publish its status to JMX
Default=0
Optional.
MonitorWithJMX
If this setting is 1, the monitoring MBean is enabled, which exposes ResponseMaster’s statistical monitoring information through JMX
Default=0
Optional.
ManageWithJMX
If this setting is 1, the management MBean is enabled, which allows stopping and restarting ResponseMaster through JMX
Default=0
Optional.
Adaptor
There can be one or more Adaptor elements, each element contains a ClassName element that specifies a class that implements the IConfigurableItem interface, and a Parameter element, which specifies the parameter to use to initialize the adaptor.
Currently, there is only one adaptor, the HtmlAdaptorMBean. It takes the port number (default=8082) it should listen on as the parameter.
4. Disposition
The disposition configuration file is used to define the processing that ResponseMaster will do after categorizing an email message. The file relates the message categories to the detailed disposition configuration files (see Section 5).
The default name and location for the disposition configuration file is “+/default.disposition.xml”.
The disposition configuration file is broken into 18 sections, one for each category and a Default section. The sections are named Default, UserReply, HardBounce, SoftBounce, OutOfOfficeReply, UnsubscribeRequest, SubscribeRequest, MailBlock, Redirect, DeliveryStatusNotification, ReadReceipt, MessageRestriction, Virus, RuleUpdate, ChallengeResponse, FeedbackLoop, NetworkInvitation, and MailboxFull. If the section for a category is empty, the settings from the Default section are used (or the parent category in the case of subcategories).
The parameters are the same for each category; they are described in the following sections.
4a. Type
The type of disposition or processing that will be done for each returned email message is listed below. One or all of these actions can be taken on a piece of email.
Possible Values:
- WriteToFile – Write an entry to a flat file for each message.
- WriteAttachmentsToDB – Writes a row to a database table for each attachment of each message.WriteToDB – Write a row to a database table for each message.
- RunSQL – Run a custom SQL statement for each message.
- MoveToSubfolder – Move the message to a subfolder.
- CopyToIMAPFolder – Copy the message to a different mailbox.
- ForwardMessage – Forward the message to another email address.
- WriteRFC822File – Writes the message into a file in the format specified by RFC 822.
- HttpRequest – Makes a GET or POST request to a URL for each message.
- FilterAndForward – Checks a rule, and if it matches, calls another disposition. Can sometimes be used instead of a custom category.
- DoNothing – Just discard the message. This is used just to be sure that you don’t make a configuration error and accidentally delete all your messages.
- Custom – Call a class that you defined in the DispositionTypesFile.
4b. DetailedDispositionFile
The name of the detailed disposition file that gives the specific parameters for the disposition. These files need to be tailored to your environment. The parameters of the detailed disposition file are listed in Section 5 of this document.
4c. DirectoryForErrors
The path to a directory that messages that cause errors should be written to. If this setting is missing or blank, disposition errors will cause the message to be retried later. If this setting is present, errors will cause the message to be written to this directory (in RFC822 format), and the message will be deleted from the mailbox that is being processed. If you discover that certain messages consistently cause disposition errors, please send them to support@extreme-messaging.com so that we can try to correct the problem.
5. Detailed Disposition
This section describes the formats of the detailed disposition configuration files for each of the disposition types that Extreme Messaging provides.
5a. Write To File
The WriteToFile disposition writes a configurable set of fields to a flat file. The file can then be loaded into a database or spreadsheet, or viewed in an editor. The “WriteToFile.writetofile.xml” sample file is an example of this type of detailed disposition configuration file.
FileName
The name of the file to write the data to.
Required.
Delimiter
The character used to separate the fields in the file.
Default= |
Optional.
WriteHeader
Controls whether or not a line that contains the field names is written to the file.
Possible Values:
- 0 – No header line is writtern.
- 1 – A header line is written each time the application starts up, and when a new file is started (if BackupInterval is not Never).
Default=0
Optional.
BackupInterval
Controls when the output file is backed-up.
Possible Values:
- Never – No matter how long the application runs, only one file is created.
- Daily – A new file is created for each day.
- Hourly – A new file is created for each hour.
- EveryTenMinutes – A new file is created every 10 minutes (new in build 729).
Default=Daily
Optional.
Note: Before build 659, this setting was called “BackupDaily” and the possible values were 0 and 1, corresponding to “Never” and “Daily” respectively.
BackupFilesToKeep
Controls the number of backup files to keep.
Only relevant if BackupInterval is not Never
Possible Values:
- 1 to 1000
Default=14
Optional.
Note: Before build 659, this setting was called “BackupDaysToKeep”.
OutputFileEncoding
Which encoding should the output file be written in.
Note: if you switch this value, you should probably rename/delete the existing file.
Possible Values:
- Any valid encoding in Java. Two likely choices are ASCII and UnicodeLittle
Default=ASCII
Optional.
TimeZone
The timezone to use when writing dates.
Possible Values:
- Any valid timezone in Java. UTC is one of them. See here for a full list.
Default=The local system timezone
Optional.
Note: This setting was added in build 701
Fields
This section contains an ordered list of Field sections that indicate which fields are written to the file.
Each field section contains the following:
Name
The name of the field.
Required.Possible Values: Please refer to the Message Fields page for more info.
MaxLength
The maximum number of characters from the field to write. If the value of the field exceeds this limit, it is truncated before being written.
Default=100
Optional.
DateFormat
The format to use for dates when writing to the file; only valid for ReceivedTimestamp and ProcessedTimestamp fields.
Possible Values: Please refer to the Date Formats section
Default= yyyy-MM-dd HH:mm:ss
5b. Write To Database
The WriteToDB disposition writes a configurable set of fields to a database table via JDBC. The “WriteToDB.writetodb.xml” sample file is an example of this type of detailed disposition configuration file.
DriverClass
The name of the JDBC Driver class.
For Oracle, it is “oracle.jdbc.driver.OracleDriver”For ODBC, it is “sun.jdbc.odbc.JdbcOdbcDriver”
For MySQL, it is “com.mysql.jdbc.Driver”
Default=sun.jdbc.odbc.JdbcOdbcDriver
Optional.
Note: Sun’s JDBC driver for ODBC does not seem to be thread- safe. If you run multiple threads, please use the database’s direct JDBC driver rather than the JDBC to ODBC bridge.
ConnectionString
The JDBC connection string to use.
If you are using ODBC, it should be of the form:
jdbc:odbc:YourDSN
where YourDSN is an ODBC System Data Source Name, created using the ODBC Administrator (available in the Control Panel).
If you are using MySQL, it should be of the form: jdbc:mysql://YourHost]:YourPort/YourDatabaseName Required.
UID
The username to use to connect to the database.
Default=null
Optional.
PWD
The password to use to connect to the database.
When you use ResponseMasterConfig to edit the configuration, this setting will be encrypted in the configuration file. If you are editing the file manually, you do not need to encrypt it.
Default=null
Optional.
TableName
The name of the table that the data should be inserted into. This table should contain a column for each field listed in the Fields section, and the column name should be the field name. It is all right if the table has more columns. ResponseMasterConfig will generate a sample “create table” statement for you that matches your parameters. Just press the “Generate create table statement” button while editing the detailed disposition configuration file.
Required.
UseMySQLEscaping
Controls how special characters in string fields are handled.
If it is 1, ResponseMaster uses MySQL escaping as described here.
If it is 0, the special characters are replaced with underscores.
We highly recommend setting this setting to “1” if you are using MySQL and you haven’t enabled NO_BACKSLASH_ESCAPES SQL Mode.
If you are having trouble with escaping characters, you can try the RunSQL disposition instead, which uses parameterized queries instead of plain SQL strings.
Default=0
Optional.
Note: This setting was added in build 683
TimeZone
The timezone to use when writing dates.
See WriteToFile for a full description.
Fields
The Fields section for the WriteToDB disposition is the same as the Fields section for the WriteToFile disposition (Write To File section).
5c. Run SQL
The RunSQL disposition runs a user-specified SQL statement via JDBC. The statement can be static, or it can have parameters. The value for each parameter is pulled from one of the message fields.
PoolSize
This disposition type is single threaded, so to provide higher throughput, we have the option of creating multiple instances of the class in a “pool” so that several SQL statements can execute concurrently.
Default=1
Optional.
Note: This setting is new in build 677.
DriverClass
The name of the JDBC Driver class.
For ODBC, it is “sun.jdbc.odbc.JdbcOdbcDriver”
For Oracle, it is “oracle.jdbc.driver.OracleDriver”
Default=sun.jdbc.odbc.JdbcOdbcDriver
Optional.
Note: Sun’s JDBC driver for ODBC does not seem to be thread-safe. If you run multiple threads, please use the database’s direct JDBC driver rather than the JDBC to ODBC bridge.
ConnectionString
The JDBC connection string to use.
If you are using ODBC, it should be of the form:
jdbc:odbc:YourDSN
where YourDSN is an ODBC System Data Source Name, created using the ODBC Administrator (available in the Control Panel).
Required.
UID
The username to use to connect to the database.
Default=null
Optional.
PWD
The password to use to connect to the database.
When you use ResponseMasterConfig to edit the configuration, this setting will be encrypted in the configuration file. If you are editing the file manually, you do not need to encrypt it.
Default=null
Optional.
TimeZone
The timezone to use when writing dates.
See WriteToFile for a full description.
SQL
The SQL to run. Place a question mark (?) every where a parameter should be inserted.
Required.
Parameters
The collection of parameters to insert into the SQL statement. This is an ordered set of Parameter items.
Optional.
Parameter
Represents one parameter to be inserted into the statement. Each Parameter contains a FieldName.
FieldName
The name of the message field to get the value of this parameter from. Please refer to the Message Fields page for more info.
Required.
MaxLength
The maximum length of the parameter. Values larger than this will be truncated.
0 means unlimited. Only relevant for string fields. New in version 659.
Default=0
5d. Move To Subfolder
After a message is processed, it will be moved from the folder being scanned by ResponseMaster to a subfolder of that folder. A different folder name can be used for each category. If the subfolder does not exist, ResponseMaster will create it at run time. The “MoveToForTechnical.movetosubfolder.xml” sample file is an example of this type of detailed disposition configuration file.
Subfolder
The name of the subfolder to which ResponseMaster should move processed email. Any folder name can be used, but for clarity we recommend that the name be similar to the category name.
Required.
PutMessageGUIDInSubject
Indicates whether or not ResponseMaster should put debugging information in the subject before copying the message. This setting is useful only for debugging.
Possible Values:
- 0 – Don’t put debugging information in the subject
- 1 – Put debugging information in the subject
Default=0
Optional.
MarkAsUnread
Should ResponseMaster mark the message as unread after moving it.
Note: some mail servers may not allow the message to be marked as unread.
Possible Values:
- 0 – The message will be marked as read
- 1 – The message will be marked as unread
Default=0
Optional.
Note: it is not currently possible to have MarkAsUnread=1 and PutMessageGUIDInSubject=1 at the same time. If this is a problem for you, please contact support to discuss the options.
5e. Copy To IMAP Folder
After a message is processed, it will be copied to a folder (or the Inbox) of an IMAP mailbox. It can be the same mailbox, or a different mailbox. If the folder does not exist, ResponseMaster will create it at run time, but the mailbox must already exist.
Host
The network name or IP address of the mail server that hosts the mailbox that you want to copy the messages to.
Required.
Port
The TCP/IP port to connect to the mailserver on. Use “-1″ for the default port (143).
Default=”-1″
Optional.
User
The username and alias used to connect to the mailbox. For MS Exchange, this takes the form
NTDomainNTusernamemailAlias
On most systems, the NTusername and mailAlias are the same, but they do not need to be.
For most other mail servers, it is simply a username.
Required.
Password
The password for the mailbox. For MS Exchange, this is the NT password of the user specified in the User setting. When you use ResponseMasterConfig to edit the configuration, this setting is encrypted in the configuration file. If you edit the file manually, you do not need to encrypt it.
Required.
Subfolder
The name of the folder to which ResponseMaster should copy the processed messages.
Default = INBOX
Optional.
PutMessageGUIDInSubject
Indicates whether or not ResponseMaster should put debugging information in the subject before copying the message. This setting is useful only for debugging.
Possible Values:
- 0 – Don’t put debugging information in the subject
- 1 – Put debugging information in the subject
Default=0
5f. Forward Message
The ForwardMessage disposition forwards the message to another email address. You can use this to forward certain categories of messages directly to Customer Service for processing. If everyone who needs access to the processed messages has access to the subfolders of the mailbox being monitored, there is no need to forward the mail. The “ForwardToTechnical.xml” sample file is an example of this type of detailed disposition configuration file.
SMTPServer
The name of the host or IP address of the SMTP server to use to when forwarding the message.
Default=localhost
Optional.
SMTPPort
The network port to use for the SMTP server when forwarding the message.
Default=25
Optional.
Note: This setting is new in build 659.
ForwardAsAttachment
If 1, the message being processed is sent as an attachment in the forwarded message. If 0, the message being processed is simply relayed to the SMTPServer specified.
Default=1
Optional.
PreserveToAddresses
If 1, the To and CC address headers of the forwarded message will be preserved, and only the RCPT TO will be changed to the values specified in the Addresses setting.
If 0, the To and CC address headers of the forwarded message will be cleared, and replaced with the values specified in the Addresses setting.
Note: If ForwardAsAttachment is 1, this setting is ignored.
Default=0
Optional.
Note: This setting is new in build 665.
PreserveEnvelopeToAddresses
If 1, the response will be sent to the SMTPServer without any changes to the To and CC headers or the RCPT TO command. This can result in loops, so be careful with the configuration of the destination SMTP Server.
If 0, the PreserveToAddresses setting will control the recipients.
Note: If ForwardAsAttachment is 1 or PreserveToAddresses is 0, this setting is ignored.
Default=0
Optional.
Note: This setting is new in build 665.
PreserveFromAddress
If 1, the From address header of the forwarded message will be preserved, and only the MAIL FROM will be changed to the values specified in the From setting.
If 0, the From address headers of the forwarded message will be cleared, and replaced with the values specified in the From setting.
Note: If ForwardAsAttachment is 1, this setting is ignored.
Default=0
Optional.
Note: This setting is new in build 665.
PreserveEnvelopeFromAddress
If 1, the response will be sent to the SMTPServer without any changes to the From address header, Return-Path header, or MAIL FROM command. This can result in loops, so be careful with the configuration of the destination SMTP Server.
If 0, the PreserveFromAddress setting will control the From header and the From setting will control the envelope from.
Note: If ForwardAsAttachment is 1 or PreserveFromAddress is 0, this setting is ignored.
Default=0
Optional.
Note: This setting is new in build 665.
IncludeCategoryInSubject
If 1, the category (e.g. “HardBounce”) is prepended to the subject of the forwarded message.
Default=0
Optional.
Note: This setting was removed in build 677.
SubjectFormat
The subject of the forwarded message. It may contain the following wildcards:
%category%
%rulematched%
%originalsubject%
Optional.
If it is missing, the default depends on the IncludeCategoryInSubject and ForwardAsAttachment settings.
Note: This setting is new in build 677.
Retries
The number of times to retry forwarding the message before giving up
Default=10
Optional.
From
The address to place in the From field of the forwarded messages. This is the address that will be seen by someone who opens the message. This should not be the email address of the mailbox that is being monitored (otherwise, you risk creating a mail loop).
Required if PreserveEnvelopeAddresses is 0, ignored otherwise.
Addresses
A list of mail addresses (in “Address” nodes) that the mail will be forwarded to.
Required if PreserveEnvelopeAddresses is 0, ignored otherwise.
5g. Write to RFC 822 File
The WriteRFC822File disposition writes the message to a file in the format specified by RFC 822. The filename comes from the MessageGUID field. You can use this disposition type if you need access to the raw message later.
RootDirectory
The root folder to place the message files into.
Default=”./output/rfc822″
Optional.
NumberOfSubfolderLevels
The number of levels of subfolders to create under the root directory. If it is 0, the files are written in the root directory. If it is 2, the files will be written to RootDirectory/a/b, for example. Set this parameter to a larger number if you expect to write lots of messages to file to avoid the problems that occur if you have 1000s of files in the same directory.
Default=2
5h. Http Request
The HttpRequest disposition makes a GET or POST request to a URL, passing a configurable set of fields.
Url
The URL to make the request to. It may contain a querystring.
e.g. “http://myhost/ProcessBounce/ProcessBounce.jsp?id=ResponseMaster”
Required.
Method
“GET” or “POST”
Default=”GET”
Optional.
UID
The username to use to connect to the URL. If it is missing, the connection is made anonymously
Optional.
PWD
The password to use to connect to the URL. If it is missing, the connection is made anonymously
Optional.
Parameters
The collection of parameters to pass to the URL.
Optional.
Parameter
Represents one parameter to be passed to the URL.
FieldName
The name of the message field to get the value of this parameter from. Please refer to the Message Fields page for more info.
Required.
ParameterName
The name querystring or form parameter to pass.
Default=The field name.
5i. Write Attachments To Database
The WriteAttachmentsToDB disposition writes a row to a database table for each attachment of each message.
DriverClass
The name of the JDBC Driver class.
For ODBC, it is “sun.jdbc.odbc.JdbcOdbcDriver”
For Oracle, it is “oracle.jdbc.driver.OracleDriver”
For MySQL, it is “com.mysql.jdbc.Driver”
Default=sun.jdbc.odbc.JdbcOdbcDriver
Optional.
Note: Sun’s JDBC driver for ODBC does not seem to be thread- safe. If you run multiple threads, please use the database’s direct JDBC driver rather than the JDBC to ODBC bridge.
ConnectionString
The JDBC connection string to use.
If you are using ODBC, it should be of the form:
jdbc:odbc:YourDSN
where YourDSN is an ODBC System Data Source Name, created using the ODBC Administrator (available in the Control Panel).
If you are using MySQL, it should be of the form:
jdbc:mysql://YourHost]:YourPort/YourDatabaseName Required.
UID
The username to use to connect to the database.
Default=null
Optional.
PWD
The password to use to connect to the database.
When you use ResponseMasterConfig to edit the configuration, this setting will be encrypted in the configuration file. If you are editing the file manually, you do not need to encrypt it.
Default=null
Optional.
TableName
The name of the table that the data should be inserted into. This table must contain five columns:
- MessageGuid varchar(36) not null
- AttachmentNumber int not null
- MimeType varchar(200)
- FileName varchar(200)
- AttachmentData image/blob
5j. Filter and Forward
The FilterAndForward disposition checks the message against a rule, and if it matches, calls another disposition.
Note: This disposition type was added in build 692.
FilterRule
The definition of the rule to check, in the same format as a normal rule. (see custom rules)Type
The disposition type to call if the message matches the rule.DetailedDispositionFile
The detailed disposition configuration file to use for the disposition.
5k. Rule Update
The RuleUpdate disposition is used update the categorization rules used by ResponseMaster. We encourages you to use this disposition type with the RuleUpdate category to automatically update the active rules and restart ResponseMaster.
Directory
The directory to place the new configuration files into. Typically, this should be ./config to allow the live rules to be updated automatically.
Required.
BackupDirectory
The directory to backup any rules found in the Directory to (in case you want to rollback the update).
Required.
Restart
- 1 – Restart ResponseMaster after receiving the new rules
- 0 – Don’t restart.
This should be 1 if the Directory setting points to the active config directory.
6. Categorization Rules
This is the file (default name=categorization.xml) that contains the master list of rules used to categorize mail. This file is maintained by Extreme Messaging and is frequently updated (and automatically changed on your system). If you believe that a change is needed to an existing rule or a new rule is required, please contact Extreme Messaging at support@extreme-messaging.com. If you need to add your own rules for specialized processing, please refer to the Advanced Topics section.
7. Categorization Rule Files
The categorization rule files contain the text matching rules that determine which messages go into which categories. Please refer to the Advanced Topics section for more information about these files.
8. Date Formats
This section describes the options that are available for the date format parameters.
| Symbol | Meaning | Presentation | Example |
|---|---|---|---|
| G | era designator | (text) | AD |
| y | year | (Number) | 1996 |
| M | month in year | (Text & Number) | July 07 |
| d | day in month | (Number) | 10 |
| h | hour in am/pm (1-12) | (Number) | 12 |
| H | hour in day (0-23) | (Number) | 0 |
| m | minute in hour | (Number) | 30 |
| s | second in minute | (Number) | 55 |
| S | millisecond | (Number) | 978 |
| E | day in week | (Text) | Tuesday |
| D | day in year | (Number) | 189 |
| F | day of week in month | (Number) | 2 (2nd Wed in July) |
| w | week in year | (Number) | 27 |
| W | week in month | (Number) | 2 |
| a | am/pm marker | (Text) | PM |
| k | hour in day (1-24) | (Number) | 24 |
| K | hour in am/pm (0-11) | (Number) | 0 |
| z | time zone | (Text) | Pacific Standard Time |
| ‘ | escape for text | ||
| ” | single quote | ‘ |
