5.12 Configuring E-Mail Notification

iManager tasks enable you to specify the e-mail server and customize the templates for e-mail notifications.

E-mail templates are provided to allow Password Synchronization and Password Self-Service to send automated e-mails to users.

You don't create the templates. They are provided by the application that uses them. The e-mail templates are Template objects in the Identity Vault, and they are placed in the Security container, usually found at the root of your tree. Although they are Identity Vault objects, you should edit them only through iManager.

This is a modular framework. As new applications are added that use e-mail templates, the templates can be installed along with the applications that use them.

You control whether e-mail messages are sent, based on your choices in iManager. For Forgotten Password, e-mail notifications are sent only if you choose to use one of the Forgotten Password actions that causes an e-mail to be sent: e-mailing a password to the user, or e-mailing a password hint to the user. See “Providing Users with Forgotten Password Self-Service” in the Password Management Administration Guide.

When you select Notify the user of password synchronization failure via e-mail, Password Synchronization is configured to send e-mail for failed password sync operations only, and only for the drivers you specify.

Figure 5-16 Configuring Password Synchronization

In addition, you need to make sure that the SMTP authentication information is included in the driver policies.

5.12.1 Prerequisites

  • Make sure that your Identity Vault users have the Internet EMail Address attribute populated.

  • If you are using e-mail notifications for Password Synchronization, make sure that the Password Synchronization driver policies contain the password for the SMTP server. See Section 5.12.4, Providing SMTP Authentication Information in Driver Policies.

  • If you are concerned that some users might not have the e-mail address populated, or if you want an e-mail record of all failure notifications, consider choosing a password administrator account that all e-mail notifications are sent to, in addition to the user.

    This e-mail address should be in the To field of the Identity Manager script policy. For more information, see Section 5.12.6, Sending E-Mail Notifications to the Administrator.

  • If eDirectory and Identity Manager are on a UNIX server, the server must hold a replica of the e-mail template objects.

    These objects are located in the Security container, at the root. This means that the server needs a replica of the root partition.

5.12.2 Setting Up the SMTP Server To Send E-Mail Notification

  1. In iManager, select Passwords > Email Server Options.

    Configure SMTP server interface

  2. Type the following information:

    • The host name.

    • The name (for example, Administrator) that you want to appear in the From field of the e-mail message.

    • The username and password for authenticating to the server, if necessary.

  3. Click OK.

  4. If you are using Password Synchronization with your Identity Manager drivers and want to use the e-mail notification feature, you must also do the following:

    1. If your SMTP server requires authentication before sending e-mail, make sure that the driver policies contain the password. See Section 5.12.4, Providing SMTP Authentication Information in Driver Policies for instructions.

      Specifying the authentication information in the Email Server Options page in Step 2 is sufficient for Forgotten Password notifications, but not for Password Synchronization notifications.

    2. Restart Identity Manager drivers that need to be updated with the changes.

      The driver reads the templates and SMTP server information only at startup time.

  5. Customize the e-mail templates as described in Setting Up E-Mail Templates for Notification.

After the e-mail server is set up, e-mail messages can be sent by the applications that use them, if you are using the features that cause messages to be sent.

5.12.3 Setting Up E-Mail Templates for Notification

You can customize these templates with your own text. The name of the template indicates what it is used for.

  1. In iManager, select Passwords > Edit Email Templates.

    List of e-mail templates in iManager

  2. Edit the templates as desired.

    Keep in mind that if you want to add any replacement tags, some additional tasks might be required. Follow the instructions in Section 5.12.5, Adding Your Own Replacement Tags to E-Mail Notification Templates.

  3. Restart Identity Manager drivers that need to be updated with the changes.

    The driver reads the templates and SMTP server information only at startup time.

5.12.4 Providing SMTP Authentication Information in Driver Policies

You specify the username and password for the SMTP server in Section 5.12.2, Setting Up the SMTP Server To Send E-Mail Notification. For Forgotten Password e-mail notifications, this is sufficient.

However, for Password Synchronization e-mail notifications, you also need to include the password in the driver policies. The Metadirectory engine can access the username, but not the passwords. The driver policy must provide it.

You must complete this procedure if the following conditions exist:

  • The SMTP server is secured and requires authentication before sending e-mail.

  • You are using Identity Manager Password Synchronization with an Identity Manager driver

  • In the Password Synchronization settings for the driver, you have selected Notify the user of password synchronization failure via e-mail.

To add the SMTP server password to the driver policy:

  1. Make sure the driver has the policies that are necessary for using Password Synchronization.

    These policies are provided in the sample driver configurations, or can be added as described in Section 5.7, Upgrading Existing Driver Configurations to Support Password Synchronization.

  2. In iManager, select Identity Manager > Identity Manager Overview.

  3. Search for the driver sets, or browse and select a container that holds the driver set.

  4. In the Identity Manager Driver Overview, click the icon for the driver.

  5. Select an Input Transformation icon or an Output Transformation icon.

  6. Select a policy, then click Edit.

  7. Click a rule.

  8. Specify the password for the SMTP server in the rules that include Do Send E-mail from Template actions.

    For example, if you are using the sample driver configurations, the following Password Synchronization policies need to be modified.

    Policy Set

    Policy Name

    Rule Name

    Input Transformation

    Password(Pub)-Sub Email Notifications

    • Send e-mail on a failure when subscribing to passwords

    • Send e-mail on failure to reset the connected system password using the Identity Manager data store password

    Output Transformation

    Password(Sub)-Pub Email Notifications

    • Send e-mail for a failed publish password operation

    The following figure shows an example of a Do Send E-mail from Template action that requires the password.

    Do send e-mail from template action, with password field for SMTP server authentication

    The password is obfuscated when it is stored in the Identity Vault.

  9. Select (mark) the rule, then click OK.

5.12.5 Adding Your Own Replacement Tags to E-Mail Notification Templates

The e-mail notification templates have some tags defined by default, to help you personalize the message for the user. You can also add your own tags.

Your ability to add tags is dependent on the application that is using the e-mail template.

Adding Replacement Tags to Password Synchronization E-Mail Notification Templates

You can add replacement tags to the e-mail notification templates for Password Synchronization, but these tags won't work unless you also define them in every password synchronization policy rule that refers to the e-mail notification template. When using a DoSendEmailFromTemplate action, all replacement tags declared within the template must be defined as child arg-strings elements of the action.

For example, Identity Manager provides default replacement tags that are included with the e-mail notification templates. Identity Manager also provides default password synchronization policies in the driver configurations. Each default tag provided with the e-mail template is also defined in each rule of the password synchronization policy that uses that e-mail template.

For example, the UserGivenName tag is one of the default tags defined in the e-mail template named Password Set Fail. A policy rule named Send e-mail on a failure when subscribing to passwords refers to that e-mail template in a DoSendEmailFromTemplate action. This rule is used in a policy to notify to a user when a password fails to synchronize. The same UserGivenName tag is defined as an arg-string element in that rule.

Like this example, each new tag you add must be defined in both the e-mail template and the policy rules that refer to the e-mail template, so that the Metadirectory engine knows how to insert the correct data in place of the replacement tag when sending the e-mail to the user.

You can refer to the tags in the Identity Manager driver configurations that shipped with Identity Manager as examples.

Keep in mind the following guidelines:

  • The items called replacement tags in the e-mail templates are called tokens in the context of Policy Builder.

  • You should use Policy Builder to make it easier to define the argument strings for the replacement tags, as explained in the steps in this section.

  • The tags you add might be defined to be any of the following:

    • Any Source or Destination attribute for the user

      Unlike adding tags for the e-mail templates for Forgotten Password, simply adding a tag that has the same name as an attribute on the User object in the Identity Vault does not cause the tag to work. As with all tags used in password synchronization e-mail notification templates, you must also define the tag in the policy that is referring to the e-mail template.

    • A global configuration value

    • An XPATH expression

    This is in contrast to tags for the e-mail templates for Forgotten Password, which are limited to eDirectory user attributes.

  • Unlike adding tags for the e-mail templates for Forgotten Password (which require you to use the exact name of an eDirectory user attribute), you can name the replacement tags any name you choose, as long as it matches the name used to define the tag in the policies that reference the e-mail template.

To define the tags in a policy, find all the policies that refer to the e-mail notification template, and use Policy Builder to add the tags to them. In each policy, edit each rule that refers to the template.

One way to make sure that you find all the policies that refer to the e-mail notification templates is to export your driver configurations, then search the XML for a do-send-e-mail action that has the template equal to the name of the e-mail notification template.

  1. In iManager, select Identity Manager > Identity Manager Overview.

  2. Select the driver set that contains the driver with the policy you want to edit.

  3. Click the icon for the driver that has the policy you want to edit.

  4. On the Publisher or Subscriber channel, click the set of policies that contains the policy you want to edit.

    For example, the driver configuration for the eDirectory driver that ships with Identity Manager contains a policy in the Input Transformation policy set which references both password synchronization e-mail notification templates.

  5. Click the policy, then click Edit.

    The following figure illustrates how to edit the Password(Pub)-Sub Email Notifications policy for the eDirectory driver:

    In the graphical view of the driver confguration, clicking a policy set gives you this popup so you can edit a policy

  6. In the list of rules that opens, click the rule that refers to the e-mail notification template.

    For example, in the Password(Pub)-Sub Email Notifications policy, you would see this list of rules. Both of these rules reference one of the password synchronization e-mail templates. You need to edit both rules if you are adding tags to both templates.

    Page showing two rules in a password synchronization policy

    If you click the first rule, the following page appears:

    Page for editing a rule

  7. Scroll to the Actions section.

    Page for editing a rule, showing the list of actions

  8. For the Do Send Email from Template rule, click the browse button Browse button for script argument builder for the Enter strings field.

    This opens the string builder. For the example rule, the following figure shows the list of strings you would see. The default tags that are used in the e-mail notification templates are already defined in the password synchronization policies that are part of the Identity Manager driver configurations, like this one. You can use the default tags as an example.

    String builder page

  9. To define a tag that you could use in an e-mail notification template, click Append New String, then enter a name for the tag.

    Make sure that the name is exactly the same name you use in the e-mail notification template.

  10. In the String value field, click the browse button Browse button for script argument builder to help you define the tag.

  11. On the Argument Builder page, specify what value should be brought in when this tag is used in an e-mail notification template.

    You can define the tag to be any of the following:

    • Any Source or Destination attribute for the user

      Unlike adding tags for the e-mail templates for Forgotten Password, simply adding a tag that has the same name as an attribute on the user object in the Identity Vault does not cause the tag to work. As with all tags used in password synchronization e-mail notification templates, you must also define the tag in the policy that is referring to the e-mail template.

    • A global configuration value

    • An XPATH expression

    The following figure illustrates how to define the tag:

    String builder page

    After you define the tag and click OK, it shows up as one of the strings in the String Builder page.

  12. Make sure you click OK to complete all the pages, so that your changes to the policy are saved.

  13. Repeat the steps to edit the rules in all the policies that refer to the e-mail notification template.

  14. Add the tag you defined in the policy to the e-mail notification template, using the exact name you used in the policies.

    At this point, you can use the tag name in the body of the e-mail notification template.

  15. Save the changes and restart the driver.

Adding Replacement Tags to Forgotten Password E-Mail Notification Templates

Using the following guidelines, you can add tags to the e-mail notification templates for Forgotten Password:

  • You can add only tags that correspond to LDAP attributes on the User object that the message is being sent to.

  • The name of the tag you add must be exactly the same as the LDAP attribute name on the user object.

    To see how LDAP attributes correspond to eDirectory attribute names, you can refer to the Schema Mapping Policy that is provided in the Identity Manager Driver for LDAP.

  • No other configuration is necessary.

5.12.6 Sending E-Mail Notifications to the Administrator

The default configuration is for the e-mail notification to go only to the user. The policies that ship with Identity Manager use the e-mail address from the Identity Vault object for the user that is affected.

However, you can configure the password synchronization policies so that e-mail notifications also go to the administrator. To do this, you must modify the Identity Manager script for one of the policies.

Send a Blind Copy to the administrator by defining the token with the administrator's e-mail address.

To copy an administrator, modify the policy that generates the e-mail (such as PublishPasswordEmails.xml, in which the policy looks up the e-mail address to send notifications) and add an additional <arg-string> element with the administrator's e-mail address.

The following example illustrates the additional arg-string element:

  <arg-string name="to">

     <token-text>Admin@company.com</token-text>

  </arg-string>

Make sure to restart the driver after making these changes.

5.12.7 Localizing E-Mail Notification Templates

Keep in mind the following:

  • The default templates are in English, but you can edit the text to use other languages.

  • The names and the definitions of the replacement tags must remain in English, so that the arg-string token definitions in the policies match the names of the replacement tags.

  • For Forgotten Password e-mail notifications only, to specify what encoding you want on your mail item, you need to add a setting in the portalservlet.properties file. For example:

    ForgottenPassword.MailEncoding=EUC-JP

    If this setting doesn't exist, then no encoding is used on the mail transformation.

  • For Password Synchronization e-mail messages, an XML attribute named charset can be specified on the following elements: <mail>, <message>, and <‘>.

    For information on using these elements, see the DirXML Driver for Manual Task Service Implementation Guide, which gives more detail on the e-mail templates.