The way in which an SMTP mail server handles errors can differ depending on your mail server implementation. For this reason, you can customize the actions that the delivery service should take when it encounters specific errors by setting up SMTP rules in an XML file.
A set of default rules for error-handling is stored in a sample file provided with IBM Cognos 8. To customize the rules, you should create a copy of this file and amend it. You then configure the delivery service to use this file.
Use the <smtpRule> tag to define an SMTP rule and the <smtpError> tag to define the error code for which you are applying a rule. For example:
<smtpRule> <smtpError> <errorCode>502</errorCode> </smtpError>
...
<smtpError>
<errorCode>550</errorCode> </smtpError>
...
</smtpRule>
Note: The priority of rules is determined by the order in which they appear in the XML file.
You can define the following types of SMTP errors:
transport errors
For example, there is no connection to the mail server, the mail server does not exist or is not configured correctly, or the user has no access to the mail server.
Use <transport>true</transport> to include this type of error in your rules.
recipient errors
For example, there are invalid recipients, too many recipients, or no recipients.
Use <invalidRecipients>true</invalidRecipients> to include this type of error in your rules.
other specified errors
Any standard SMTP error code generated by the mail server.
Use <errorCode>nnn</errorCode> to include this type of error in your rules.
The following actions can be performed for each error type, and are defined as behaviors in the XML file:
resend behavior
Specifies how many times to resend an email (n) and the resend interval in seconds (x).
Use <resends number="n" delaySeconds="x" /> to apply this behavior.
Note: To resend an email indefinitely, use <resends number="-1">.
keep mail behavior
Specifies whether the delivery service should keep the failed email in a separate queue after it has been resent the required number of times and is unsuccessful. The queue is named SMTPBackupQueue.
Note: No further action is performed on emails in the backup queue. To add emails from SMTPBackupQueue to the regular SMTPQueue, you must change the queue name in the database table and restart the server.
Use <keepMail>true</keepMail> to apply this behavior.
fail mail behavior
Allows you to customize the email notification that is sent when an email delivery has failed.
Use the <failMail> tag to apply this behavior.
There are two further optional attributes you can use to specify the email notification subject (<subject>) and recipient (<recipients>).
Tip: If you omit these tags, the email notification is sent by default to original recipients list with the subject "Send failed:".
To remove all current recipients, use <recipients sendToCurrentRecipients="false">.
To send an email notification to the agent owner, use <owner>true</owner> and, if required, use <recipient address="name@address.com"> to specify an email address.
default behavior
Defines the action to perform when no matching rule is found.
Use the <defaultSmtpBehaviour> tag to apply this behavior.
The first example shows how to set up a rule for the default behavior. Here, the delivery service attempts to resend the undelivered email three times at hourly intervals. If it is unsuccessful, it sends an email notification using the default fail mail behavior.
<defaultSmtpBehaviour> <smtpBehaviour name="default"> <keepMail>false</keepMail> <resends number="3" delaySeconds="3600" /> <failMail /> </smtpBehaviour> </defaultSmtpBehaviour>
The second example shows how to set up a rule for a transport error. Here, the delivery service resends the email indefinitely, at 30 second intervals, until it is successful.
<smtpRule> <smtpError> <transport>true</transport> </smtpError> <smtpBehaviour name="transport"> <keepMail>false</keepMail> <resends number="-1" delaySeconds="30" /> </smtpBehaviour> </smtpRule>
The third example shows how to set up a rule for a recipient error. Here, the email notification is sent to the agent owner using the email address stored in their user ID. The original email recipients are removed from the recipient list.
<smtpRule> <smtpError> <invalidRecipients>true</invalidRecipients> </smtpError> <smtpBehaviour name="invalidRecips"> <keepMail>false</keepMail> <failMail> <recipients sendToCurrentRecipients="false"> <owner>true</owner> </recipients> </failMail> </smtpBehaviour> </smtpRule>
The fourth example shows how to set up a rule for a specified error code. Here, the undelivered email is sent to the backup queue whenever error 550 occurs. It remains there until you process it manually. A customized email subject is set up for the fail mail notification.
<smtpRule> <smtpError> <errorCode>550</errorCode> </smtpError> <smtpBehaviour name="specialErrorCode-550"> <keepMail>true</keepMail> <failMail> <subject>Error code 550 keep mail</subject> </failMail> </smtpBehaviour> </smtpRule>
Copy the c8_location\configuration\smtpRules-sample.xml file to the c8_location\webapps\ p2pd\WEB-INF\classes folder.
Note: To use your own file rather than a copy of the sample file, copy it to the same folder.
If you are using the sample file, rename the copied file to smtpRules-custom.xml.
Open the required file in an XML or text editor.
Amend the file to customize the rules.
Start IBM Cognos Connection.
In the upper-right corner, click Launch, IBM Cognos Administration.
On the Status tab, click System.
From the All Servers drop-down menu, click Services, Delivery.
From the drop-down menu next to DeliveryService, click Set properties.
Click the Settings tab.
Next to Environment, click Edit.
In the Parameter column, type the parameter name smtp.rules.properties.location.
In the Value column, type the name of the customized xml file you are using.
In the Parameter column, type the parameter name smtp.rules.properties.reread.
Although not mandatory, it is useful to set this parameter for testing purposes so that the SMTP rules are read for every request.
In the Value column, type true.
Click OK.
In the Set properties page, click OK.
When you have finished testing the rules, you must reset the smtp.rules.properties.reread parameter.
Repeat steps 5 to 11 to access the advanced settings.
In the Value column for the smtp.rules.properties.reread parameter, type false.
Click OK.