There are as many ways to set up your email directories as there are to set up a computer. This section discusses several ways to do it and the advantages of each.
The bottom line is that APS (actually, APSMail) must be able to locate its mail files. Each event that can be responded to via email has, in the APS.cfg file, the name or path of an email file. A set of directories where these files reside can also be configured in APS.cfg.
The simplest configuration is to just specify the entire path of each file for each event. Put each file wherever it is most convenient, whether they exist on the same directory, a directory specific to APS email files, or anywhere else is immaterial. APS can find them, since the full path is specified in the configuration.
This configuration, while the simplest, is also the least flexible and, possibly, the most difficult to maintain. A given event will be always responded to using the same file, with the same content, regardless of the user, user type or situation. The only controlling factor for the content is the event itself.
In addition, the files could be scattered across your drive, creating confusion, as they may intermingle with other files.
CA recommends that a site create a specific APS email directory, possibly with subdirectories (discussed later). All files should exist within (or under) this directory. The directory should be specified as the mail directory in the APS.cfg file.
Many sites limit their thinking of email to just sending mail to users. There are other uses as well. For example, sites can send mail to administrators when expiring certain users so that a customer service department can proactively contact the user. Another example: using third party tools, administrators can be paged if a user is disabled due to a failure count problem (thus alerting the administrator to a possible denial of service attack).
A useful technique is to embed a user attribute into the file name or the path. This is most used to send different files based on the user's language. Thus, the mail directory might be specified as:
/mail/{preferredLanguage}/
In this case, APS will replace {preferredLanguage} with the value stored in the target user's profile (such as EN or FR).
This technique can also be used to send different files based on other information about the user, such as the user's type or the Line of Business of the user. This is usually done within the file name rather than the directory, such as:
PasswordWarning_{userType}.email
When the user's attribute userType contains Administrator, the file PasswordWarning_Administrator.email will be sent.
Some words of warning when using embedded attributes:
The purpose of APSMail is to dynamically format messages and deliver them into a mail system; it is not APSMail's purpose to actually deliver the mail or to track it once routed to an SMTP server. SMTP, by its very nature, is an asynchronous delivery method and APSMail is not part of the SMTP "network".
SMTP servers can be configured to retry sending, log errors, archive mail, etc., these are not the responsibilities of APSMail. APSMail will format the message and the network architecture should be designed so that APSMail can hand off that message to an SMTP server as fast and as reliably as possible.
SMTP servers are typically free of charge. UNIX and Windows Servers include them. SMTP servers do not usually consume large amounts of resources (full email servers can, but not just SMTP servers).
CA recommends that an SMTP server be installed on the same machine with APSMail, if at all possible. This will completely eliminate the network between APSMail and the SMTP server, reducing the network latency to almost nil and removing a point of failure from the entire data flow.
From there, the SMTP server can be configured to retry, etc, to provide maximum fault tolerance in the event that the internet is inaccessible, etc.
Once APSMail delivers the message to the SMTP server, the connection is dropped and the APSMail code moves on. The result is logged (if logging is turned on) and the message is completely forgotten. If the mail is not delivered to the ultimate recipient, or there is a delay, the SMTP network is responsible for notification, not APSMail. You can configure, using the email templates, the information that you want APSMail to pass to the SMTP server how you want errors reported, but all such reports are through the SMTP system itself and do not involve APSMail.
The [REM] (or [COMMENT], if you prefer) directives consume a small amount of disk space and a minimal amount of processing time, yet they are easily the most useful and used (yet not used enough!) directives available for email templates.
Any line beginning with [REM] will be completely ignored by APSMail. This allows a site to put information about why certain directives have certain settings and allow a site to keep a change log for that file.
Comments are not sent to the SMTP server and are not placed into the LOG file.
The [INCLUDE] directive, available for email template files, can be used to "hide" machine-specific details about email delivery. Thus, such things as the SMTP server, the login information for that email server, and return/delivery receipt information, can be localized and stored separately on each machine, then all of the email templates, in all environments (development, test, staging and production) are identical, only a master INCLUDE file differs.
This master include file is sometimes referenced by an environment variable within the template actually used. This shields the email templates from differences in the file system structures:
There are actually two different ways to perform localization of mail. Both methods require multiple template files, one for each locale to be supported by the site.
The first mechanism, which was the only mechanism available prior to the release of APS 5, was to use different email templates, each entirely self-contained and each in a different supported language. Sites then place subdirectories under the mail directory for each language, named with the ISO code for that language.
In each application, the email template to use are then referenced with the ISO code to use as part of the file name, specified as an attribute lookup, as in:
Password Expired Email={preferrendLanguage}/PExpire.etf
During the file resolution (assuming that the application support attribute lookup), the reference to {preferredLanguage} would be resolved to whatever (assumed to be ISO code) is stored in the (LDAP) user record and the correct email template would be used (assuming it is available).
The second method, newly available to APSMail, is very similar, but allows sites to centralize the directives used for the mail with liberal use of the [INCLUDE] directive.
Password Expired Email=PExpire.etf
Then each include file contains the locale-specific information.
Neither APS nor APSMail "know" users' email addresses. When you specify where email is to be sent (using the [TO] notation described later in this chapter), you can specify an explicit email address, such as:
[TO] APS-Support@netegrity.com
Or you can reference a user attribute, using the "{" and }"} notation, such as:
[TO] {mail}
Just keep in mind that an attribute called mail will be used. If there is no such attribute {mail} will be used as the mailing address (which will probably not work).
If your site uses multiple User Directories and the name of the attribute is not consistent across directories, use the [MAPPING] section of the APS Configuration File to create a common name for all directories and use the common name here.
Return and From addresses can be specified in the body of the mail file. These addresses may or may not actually exist (though if a reply to address does not exist, end users will receive an undeliverable mail notification if they reply to mail).
It is very useful to specify generic alias addresses for these values. Thus, the Reply To address could be password-support@MySite.com. Within the site's mail server, this address would be an alias pointing to a "real" email address, representing the person actually performing the support. It is better to use an alias than a real address for this purpose, so that the support person can be changed without changing the email files and any mail that has already been sent will still point to a valid address.
Sometimes the mail address for a user will be invalid. It may never have been entered correctly or the user's address may have changed and the change has not been reflected in your directory. In these cases, email will be undeliverable (it will "bounce"). A site should be able to gracefully handle this condition.
The easiest way to handle these cases is to set up a dedicated mail server to handle APS mail (if the site has enough volume to warrant it). This server should have a legitimate postmaster defined. Bounced mail notifications will be sent to the postmaster (which is usually an alias rather than a specific email address). A support representative can review these notifications and address each one individually. It is impossible for APS (or APSMail) to handle this condition itself, since mail is submitted to the mail server for delivery at some point in the future. By the time that it is discovered that the mail is undeliverable, APS has long advanced to other things. Sometimes, such detection may not take place for days!
The Errors-To feature can be used, but be forewarned, many mail servers do not support this feature.
Each mail file should contain all of the information required to send the file, with the exception of the information about the mail server (which is stored in the APS Configuration File or environment variables).
APSMail has a very simple, yet strict, format for email template files.
The template file may contain references to user attributes and/or macros. APS fully supports this feature of APSMail as follows:
As each line is read from the file, the line will be examined. Any text surrounded by curly braces ("{" and "}") will be treated as an attribute query (lookup). That is, the text within the braces will be used as an attribute lookup (using code similar to the SiteMinder userattr response) and then replaced (along with the braces) with the returned values. Note that if the user does not have a value for the attribute, the braces and attribute name will be removed. They may appear anywhere in the line and are case-insensitive. They may not span multiple lines, though the replacement text may contain embedded newline characters.
APSMail, called by APS, supports macro expansion. These are values supplied by APS and are not stored in the User Directory. If they appear in the line, they will be replaced by the appropriate value. They may appear anywhere in the line and are case-insensitive. Macros are surrounded by percent signs ("%").
The macros supported by APS include:
|
%DAYSLEFT% |
The number of days left before the user's password expires (calculated by APS). This value is only available when a password change warning is being issued. |
|
%PASSWORD% |
For password change confirmations only, this macro is replaced with the user's new password. In general, this macro should not be used. |
The macros supported by FPS include:
|
%MESSAGE% |
For error mail, this contains the text of the error message. |
|
%PASSWORD% |
During confirmation, this is the clear text password for the user. You cannot use {userPassword} (which would return the LDAP value), since the returned value would be encrypted. |
|
%HALFPASSWORD1% |
The first half of the new password, in clear text. One secure way to transmit the new password to the user is to send half of the password via email and to display the other half on the browser. This macro allows you to include the first half of the password via email. |
|
%HALFPASSWORD2% |
The second half of the new password, in clear text. One secure way to transmit the new password to the user is to send half of the password via email and to display the other half on the browser. This macro allows you to include the second half of the password via email. |
Replacement macros and attributes are also supported in file names, though a Unix site must be very careful with case sensitivity in file names. This can be useful for supporting multiple languages or special mails by user type.
This example might be used as the English language warning mail under APS.
[FROM] SiteMinder Administration
[TO] {mail}
[RE] Your password to our site will expire
[REPLYTO] HelpDesk@oursite.com
Your password on our site will expire in %DAYSLEFT% days. In order to maintain your access to our site, you must change your password before it expires.
To change your password, you can go to http://www.yoursite.com/CPW/SmCPW.exe
Many APS sites have found a considerable advantage to putting a dedicated SMTP (mail) server on each SiteMinder Policy Server. Some of the benefits include:
|
Copyright © 2014 CA.
All rights reserved.
|
|