This section contains the following topics:
APSMail is the library used by APS to send email, via an SMTP (Simple Mail Transfer Protocol) server, based on dynamic instructions in a mail template.
The APSMail library is designed to be called from APS; its programmatic interface is not public. However, a command line program is provided so that email templates can be sent from the command line, ostensibly for testing.
The Simple Mail Transfer Protocol (SMTP) provides a method to exchange electronic mail messages. The SMTP protocol exchange is very simple, as suggested by the protocol name. It is one of the very earliest of the internet protocols and has not changed significantly, due to its extremely wide use and installed base.
An SMTP client wishing to exchange mail with an SMTP server contacts the server on the well-known service port. The SMTP protocol is a simple ASCII, line-oriented command/response protocol. Each command is a simple command name followed by some parameters, depending on the command. Responses consist of a three-digit numeric code followed by a string explaining the response. The numeric code is easily processed by the client software and the error string can be passed on for human interpretation. Note that responses can appear on more than one line (provided the server sends the appropriate indicator).
After contacting the server, the client waits for a simple greeting message from the server. When the client receives the message, it sends a HELO (or EHLO, for Extended SMTP) command identifying itself. Further commands identify the sender and recipients and transfer the message data itself.
ESMTP, or Extended Simple Mail Transfer Protocol, is a relatively recent update to the SMTP specification that is fully backwards compatible with older SMTP clients.
APSMail communicates using RFC compliant SMTP and ESMTP, with a few optional extensions.
The original SMTP protocol is defined in RFC 821. Related RFCs include 1869 (ESMTP), 822 (Format of Electronic Mail Messages), 1521 (MIME), 1725 (POP3), and 1730 (IMAP4).
As stated above, SMTP (and ESMTP) is a line-oriented, ASCII protocol. By its very nature, it is quite slow, compared to most network protocols. While APSMail has been architected to maximize performance, this performance limitation should be taken into consideration when implementing a site.
Network latency can be significant. This is the time taken to locate and set up/tear down connections to the SMTP server.
Mail Services are designed to be distributed, a network of servers interconnected and routing information between them. APSMail is not a server/router, but rather just a client that submits messages into this network for delivery.
As such, it need not have access to specific SMTP servers, just a single server that provides an access point to the internet mail "network". In network parlance, this would be an "email gateway".
An SMTP server is a relatively lightweight service; it is for the submission of messages only, not for reading messages. As such, they do not consume large amounts of resources on the machines that they are running on. They are also relatively inexpensive, cost-wise. Microsoft Windows™ NT server, Windows 2000™ Server and Windows XP™ Server all include an SMTP server. Almost all flavors of UNIX include one as well.
To minimize network latency (and to improve fault tolerance, as discussed below), CA recommends that an SMTP server be installed and operational on the same machine where APSMail is running. In this configuration, all communications between APSMail and the SMTP server are local to the machine; no external network traffic is required. The SMTP server, after accepting the message, will communicate with the rest of the mail "network" transparently to APS. If this SMTP server will be used exclusively by APSMail then a site should configure the server to not allow access from other hosts.
SMTP servers, by their very nature, are store and forward servers. This means that it will accept messages and hold them until they can be delivered (SMTP servers are configured to retry, etc, as necessary to keep attempting delivery).
APSMail is not an SMTP service. It does not have the capability to retry sending a message if the initial send fails, that is the function of the SMTP server. A well-architected site will be designed to get the message from APSMail to the SMTP service as quickly and robustly as possible and utilize the SMTP server's own fault tolerance.
To this end, CA recommends that the SMTP service and APSMail be running on the same machine (also as mentioned above for performance). Thus, network outages, machine outages, etc, will not impact APSMail delivery.
APSMail is designed to run in either a server (multi-threaded) mode or from a command-line type mode. Each has its own resource conservation requirements. APSMail is designed to be somewhat resource conservative; that is, it makes every attempt to conserve limited machine resources, memory in particular.
This may cause slight performance degradation and creates the potential for a small fault tolerance problem.
APSMail also puts no restrictions on the number of connections to a given SMTP server. However, some SMTP servers do restrict the number of connections from a given host. This may mean that a site has to configure their SMTP service to remove this restriction. For example, if an SMTP server restricts a given client to 10 connections, but APSMail, running under a SiteMinder Policy Server, needs to send eleven pieces of mail at once, the eleventh send may fail because the SMTP server rejects the eleventh connection (there are all kinds of timing considerations that come into play). This is yet another reason to have a "private" SMTP server dedicated to each instance of APSMail.
APSMail is designed to be integrated with APS and can be configured in numerous ways. APSMail has a specific, predefined precedence system for resolving configuration conflicts.
At the highest level, APSMail can be configured using environment variables. These settings will be used unless overridden elsewhere. Most of these settings can also be made within APS. Some may also be specified or overridden within the email template files (as described later in this chapter).
This environment variable can be used to override the name of the local host as transmitted to the SMTP server in the HELO (EHLO) message. If not specified, it can be overridden in an email template file. If still not set, APSMail will use the network name of the local machine.
This environment variable specifies the IP or network name of the SMTP server. It can be overridden within the APS.cfg file and again in email template files. If not specified anywhere, mail will not be sent.
This variable specifies the email address to send to the SMTP server in the MAIL FROM command. Under the older SMTP protocol, this amounts to the login id for the SMTP server and need not match the FROM address for the message itself.
Some SMTP configurations require that this address be known to the SMTP server.
This can be overridden in an email template. If not specified at all, the FROM address of the email template will be used.
Specifies the path to an APS "send" log file, where information about sent (and rejected) mail is written. This value can be set within the APS.cfg file and from within a template. If not specified, no send log will be maintained.
This specifies a list of directories where APSMail should look for mail template files. Multiple directories can be specified. Under Windows, directories are separated by semicolons; on UNIX, directories should be separated by colons.
This value can be set in the APS.cfg file. If not specified, APSMail will not search for files; it will try to open them as configured to APS.
This environment variable specifies the name of a file where all communications between APSMail and the SMTP server(s) should be logged. Note that this file can get quite large, so it should not be used except for troubleshooting. If not specified, no communications log will be kept. This is the only way to turn on the communications log.
APSMail sends mail as defined by an email template file. Everything that APSMail needs to know to construct and send the message can be defined within the template.
Template files are simple ASCII text files; they require no specific editor or tools to operate on. Text lines may be terminated with either carriage-return/linefeed pairs or merely linefeeds (so the differences between Windows and UNIX are not significant).
A template file contains the body of the message to send, along with directives that control how the message is sent and related operations. In addition, embedded within the text can be references to macros and lookups.
Each email template file should contain all of the information required to send the file. Some settings may or may not be required by your mail server.
As each line is read from the file, the line is examined to see if it certain text must be replaced with other text ("macros" or "lookups"). After replacement, if a line in the file begins with one of the directives described in the following sections, it will not be used as part of the message body and the text following the keyword will be used as described. Note that replacements references (macros and attributes) are replaced in these lines.
Everything else is considered part of the message body.
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.
Macros are named values. That is, a name represents a value that is determined at a later time or in a different place.
APSMail allows the use of three different kinds of macros: Application, Define and Environment variables.
A macro reference may appear anywhere in the email template file or in a template file name or path. Before processing a file name or path, any macro references contained within the path are replaced with their value. Similarly, as each line is read in from a template file, any macro references are replaced with their current value.
Application macros are defined by the calling application and are usually context specific. For example, when sending Password Expiration Warning email, APS exposes a DaysLeft macro so that the email can contain the number of days before the password actually expires. See the application's documentation to determine what application macros are available in each context.
Application macros can be referenced in three ways: as %<macro name>%, {macro: <macro name>} or as {%<macro name>}. All are equivalent, but the first form is deprecated and is being phased out.
Using the prior example, in an APS Password Expiration Warning email, the text might read:
Your password will expire in {%DaysLeft} day(s). Please change it before that time.
Macros can also be defined within the template files themselves using the [DEFINE] directive (discussed later in this chapter). This is typically used with the [INCLUDE] statement to specify settings.
Define macros are referenced in exactly the same way as application macros.
[DEFINE SMTPServer] 127.0.0.1
[MAIL SERVER] {%SMTPServer}
Environment variables can also be referenced within an email template file. The syntax is very slightly different. Instead of a percent sign ("%"), use a dollar sign ("$").
[MAIL SERVER] {$OUR_MAIL_SERVER}
Several alternate formats can be used for referencing environment variables. All of the following are also supported, but not recommended (the second form is deprecated).
[MAIL SERVER] {env: OUR_MAIL_SERVER}
[MAIL SERVER] %ENV_OUR_MAIL_SERVER%
APSMail also supports Lookups. When APSMail encounters a lookup, it calls back into APS to get a value for the lookup. This is typically done to retrieve values from the user record.
Note that lookups are supported by the APS, not APSMail directly.
Lookups are referenced within curly braces. There are two forms:
{<attribute>}
This form generally represents a raw data field from the default user record. For example, {cn} would typically be replaced with the value of the cn attribute of the user.
Another form of a lookup reference is
{<qualifier>:<attribute>}
This form has specific, application-defined uses. For example, if there is more than one user involved, an application might have a qualifier of "Administrator", in which case "Administrator:cn" refers to the common name of the administrator instead of the common name of the user.
APS docs not currently support any qualifiers.
In most cases, if the first form of lookup is supported, you can use the well known SiteMinder attributes as well as attributes that reside in the user directory itself.
The Well Known attributes are documented in the SiteMinder manuals and include such things as the user's IP address (only useful if sending mail while a user is currently online).
The email template file contains directives that tell APSMail how to send the message. Each directive appears on a single line and must start at the beginning of the line. The entire line is considered part of the directive and will not be included in the message body. Anything that is not a directive will be included in the message body.
All directives are surrounded by square brackets ("[" and "]") and start at the beginning of the line. Directives may appear anywhere in the file, but the file is only processed once, so directives that have an effect on file processing will only affect from the point where they appear in the file.
Some directives may appear more than twice and will be processed for each appearance (such as the ATTACH directives). Other directives should only appear once; if such a directive appears more than once, the last instance will be used.
A directive can reference macros and lookups.
Example:
[INCLUDE] <path>
The Include directive tells APSMail to include the file specified and process its contents as though it appeared at that same point in the original template. Included files may include other files, but APSMail will detect if the same file is included recursively and will issue an error.
The <path> is not processed in any way (the search paths are not used), it is merely opened directly. Most systems should use an environment variable (as a macro) to identify the location of this file.
[INCLUDE] {$MASTER_MAILFILE}master.etf
Example:
[DEFINE <name>] <value>
This directive allows a site to create definitions of symbols (<name>) representing a value (<value>). If <name> is represented elsewhere in the file (below the point where the [DEFINE] directive appears), the reference is replaced with the value. For more information, see Define Macros.
Lookups can be used in Macro definitions.
Macros are only "visible" from the point at which they are defined.
Example:
[COMMENT] <text> [REMARK] <text> [REM] <text>
Any line containing this directive is completely ignored. It is useful for placing comments into the template file to ease maintenance or to temporarily disable other directives in the file.
[REM] Last updated by John Smith on 4/1/2003 [REM] Test sending synchronously - [ASYNCHRONOUS]
Example:
[LOGPATH] <path> [LOG PATH] <path>
This directive specifies a path where the result of this send should be logged. This overrides both the application and environment variables. It is not often used. It might be used, however, if different templates are to be logged to different files.
Example:
[MAILSERVER] <server> [MAIL SERVER] <server> [SMTPSERVER] <server> [SMTP SERVER] <server> [SERVER] <server>
This directive overrides both the environment variable and any application-specified mail server to tell APSMail where to find the SMTP server. If no SMTP server is specified, then no message will be sent.
This directive is frequently used in a centrally included template file.The <server> may be specified as an internet machine name or an IP address. It may also be followed by the port to use, separated from the server address by a colon, as in smtp.acme.com:50 or 127.0.0.1:50. It is very unusual to use a port other than the default SMTP port.
Example:
[TIMEOUT] <seconds>
This directive specifies the amount of time to wait for mail server responses. By default, APSMail will wait up to 30 seconds for a response from a mail server. This value must not be zero.
Shorter values do not improve performance in any way.
If this value is too low, it may cause APSMail to prematurely decide that a server is not responding and will result in errors. If too high, real errors from the server will not be detected for some time.
[TIMEOUT] 60
Example:
[LOCALHOST] <hostname> [LOCAL HOST] <hostname> [STATION] <hostname> [HELLO] <hostname> [HELO] <hostname> [EHLO] <hostname>
This directive specifies the name to use on the mail server greeting message. Per the SMPT RFC, this should be the name of the local host. If not specified, APSMail will look up the name of the local host. This can also be specified in an environment variable, but any value appearing in this directive will override an environment setting.
SMTP supports a single security option. ESMTP requires the MAIL FROM command (like SMTP), but also provides two other alternatives for security. At this time, APSMail does not support these additional security options. If the SMTP service is local to the APSMail service, these options are not needed.
Example:
[MAILFROM] <email address> [MAIL FROM] <email address>
This directive specifies the email address to send to the mail server in the MAIL FROM command. All servers require MAIL FROM. Some require that the address be known to the server or that the address be in the same internet domain as the server.
The value used for MAIL FROM can come from a variety of places if not specified in an explicit directive. The APSMAIL_LOGIN environment variable will be used if this value is not set.
If it is not explicitly set by the environment variabl and this directive does not appear, then the value from the SENDER or FROM directives will be used.
[MAIL FROM] administrator@acme.com
Example:
[FROM] <email specifier>
This directive specifies the FROM address of the message. If not set, the SENDER will be used. This value is used in the FROM header of the message. If different from the SENDER, some email clients will show one or the other or a combination of both the FROM and SENDER headers.
This is supposed to be (according to the RFC) only used to display who the message was from. However, its misuse has caused some email clients to perform special processing, if different.
The <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
Example:
[SENDER] <email specifier>
This directive specifies the address of the sender of the message. If not set, the FROM address will be used. This value is used in the SENDER header of the message. If different from the FROM, some email clients will show one or the other or a combination of both the FROM and SENDER headers.
This is supposed to be (according to the RFC) used to record who the actual sender was, for purposes of error handling and replies. However, its misuse has caused some email clients to perform special processing, if different.
The <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
Example:
[SUBJECT] <text> [RE] <text>
This directive tells APSMail the subject line to use for this message.
[SUBJECT] Your password will expire in {%DaysLeft} day(s)
Example:
[TO] <email specifier(s)>
This directive tells APSMail who to send the message to directly (as opposed to copies). More than one address can be specified, separated by semi-colons.
These addresses are used in the TO header of the message as well.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
[TO] {mail};{pagermail}
Example:
[CC] <email specifier(s)>
This directive tells APSMail who to send copies of the message to. More than one address can be specified, separated by semi-colons.
These addresses are used in the CC header of the message as well, so they are visible to all message recipients.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com [CC] helpdesk@mycompany.com
Example:
[BCC] <email specifier(s)>
This directive tells APSMail who to send copies of the message to. More than one address can be specified, separated by semi-colons.
These addresses are not visible to message recipients.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com [BCC] audit@mycompany.com
Example:
[REPLYTO] <email address> [REPLY TO] <email address >
This directive sets the REPLY-TO header in the message. If a reply is sent to the message, the reply is to go to this address instead of to the sender.
The <email address> should be an internet email address.
[REPLY TO] helpdesk@mycompany.com
Example:
[ERRORSTO] <email specifier> [ERRORS TO] <email specifier>
This directive sets the ERRORS-TO header in the message. Some mail servers will use the email address specified in this header to send delivery error messages to. If this directive is not specified, errors are sent to the sender or reply-to address.
The <email address> should be an internet email address.
[ERRORS TO] helpdesk@mycompany.com
Example:
[RETURNRECEIPT] <email address> [RETURN RECEIPT] <email address> [RETURNRECEIPTTO] <email address> [RETURN RECEIPT TO] <email address>
This directive specifies that read receipts are requested from each of the recipients of the message. Read receipts are only expected to be sent when the message is marked as read by the user of that client.
There is no guarantee that the client program will actually send such a receipt. Email clients can usually be configured to suppress, prompt or automatically return such a receipt. This directive therefore can only request such a receipt.
The <email address> is optional. If not included, then no specific address will be included with the message and any return receipt, if sent, will be sent to the sender of the message. It should be just an internet address, not a full email specifier.
[RETURN RECEIPT] audit@mycompany.com
Example:
[DISPOSITION] <email address> [DISPOSITIONNOTIFICATION] <email address> [DISPOSITION NOTIFICATION] <email address> [NOTIFICATION] <email address> [DISPOSITIONTO] <email address> [DISPOSITIONNOTIFICATIONTO] <email address> [NOTIFICATIONTO] <email address> [DISPOSITION TO] <email address> [DISPOSITION NOTIFICATION TO] <email address> [NOTIFICATION TO] <email address> [NOTIFY] <email address>
This directive specifies that delivery receipts are requested from each of the recipients of the message. Delivery receipts are usually sent by the email SERVER that delivers the message to the email client. While servers can be configured as to whether they return these receipts or not, it is more likely that such a request be honored.
There is still no guarantee that such a receipt will actually be sent. This directive therefore can only request such a receipt.
The <email address> is optional. If not included, then no specific address will be included with the message and any receipt, if sent, will be sent to the sender of the message. It should be just an internet address, not a full email specifier.
[NOTIFY] audit@mycompany.com
Example:
[ORGANIZATION] <text>
This directive sets the ORGANIZATION header in the message. This is a relatively new header in the SMTP specification. Most clients just display its contents.
[ORGANIZATION] Acme, Inc.
Example:
[PRIORITY] LOW [PRIORITY] LO [PRIORITY] NORMAL [PRIORITY] NORM [PRIORITY] HIGH [PRIORITY] HI
This directive sets the message priority. This has little to do with message handling at any point in the delivery of the message. It is typically used by the email client reading the message to determine how to display it.
[PRIORITY] HIGH
Example:
[TEXTMODE] PLAIN [TEXTMODE] ENRICHED [TEXTMODE] HTML
This directive tells APSMail the format of the message body. APSMail will encode the body as required by this directive and set the MIME type of the message accordingly. If this directive is not specified, PLAIN is assumed.
APSMail is not involved with the formatting of the message body, this setting merely tells the system what MIME type to use. The development of mail content using ENRICHED or HTML formatting is completely up to the site.
Example:
[CHARSET] <ISO-character-set-identifier>
This directive tells APSMail what character set to associate with the message body and to use for plain text character quotation. By default, ISO-8859-1 is used.
APSMail does no edit checking on this value.
Example:
[X-<name>] <value>
The Electronic Mail Format specification allows for extensions to the message headers in the form of what are called X-Headers. These headers are in the form of X- + <some name text> + ":" + <some value>. If a client does not know how to process such a header, it is merely carried along and ignored.
APSMail automatically inserts a single X-header, called X-Mailer, which identifies the version of APSMail used to generate the message.
Additional custom headers can be included in the message as well using this directive. Header names in this context are case-sensitive.
A blank <value> will suppress a particular header, so, for example,
[X-Mailer]
will suppress the sending of the APSMail header.
Anything not on a directive line contained in a template file (or included template files) will be added to the message body. This includes blank lines!
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:
APSMail writes to the SiteMinder Policy Server log when running under the Policy Server.
APSMail will log errors and confirmations to this log. The first troubleshooting action should be to examine this log, if available. Error messages are self-explanatory and are usually followed immediately by a recommended action.
This is usually good for finding mail options and server handshake problems, such as invalid email addresses, server connectivity issues and server login problems.
If the LogPath is specified to APSMail, each transmission is logged as a block entry describing where the message was sent, the content of the message and the ultimate result of the send.
This log is good for reviewing the results of the transmission and the formatting of the body of the message. Message headers are also shown.
For each message, a block like the following is recorded.
The first section of each log block is information about the actual transmission. This block identifies the server and connection information and the result of the send.
The second block identifies the message header and includes such items as who the message was from and who it was sent to.
The third block is the formatted message body.
Further blocks identify the attached files, if any, and the identified MIME types of each file.
APSMail will write a log containing detail about its actual communications with the mail server. This is turned on by setting an environment variable called APSMAIL_COMMLOG to identify the file to which the log should be written.
This communications log can get very large, since it will show the transmission of attachments (which can be arbitrarily large) and will show encoded data. Generally, this log should not be enabled, unless troubleshooting problems with server communications.
The best way to troubleshoot formatting problems is to start with the Send Log, since it will show the formatted message as sent to the mail server. The message might be base 64 encoded on transmission, in which case the communications log will not be human readable.
Most formatting problems are caused by either using the wrong TEXTMODE directive or by using macros/lookups that can change the visual formatting.
If APSMail is showing that the message was accepted by the server, yet the recipient does not get the message, then troubleshooting the mail system is required.
APSMail passes the message to the SMTP server and then forgets about it. All delivery is done by the mail server, not APSMail, at that point. If the SMTP server accepts it, any problems with delivery will either be recorded by the mail server(s) or through delivery notification.
|
Copyright © 2013 CA.
All rights reserved.
|
|