Configuring E-Mail Notification

The iManager role named Notification Configuration lets you 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 eDirectory, and they are placed in the Security container, usually found at the root of your tree. Although they are eDirectory objects, you should edit them only through the iManager interface.

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.

Identity Manager provides templates for Password Synchronization and Forgotten Password notifications. You control whether e-mail messages are sent, based on your choices in the iManager interface.

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-mail password to user, or e-mail password hint to user. The page you use to set this option is shown in Providing Users with Forgotten Password Self-Service.

Password Synchronization is configured to send e-mail only for failed password sync operations, and only for the drivers you specify. The page you use to set this option is shown in the last figure in Password Synchronization Settings You Create Using Global Configuration Values. In addition, you need to make sure the SMTP authentication information is included in the driver policies.

In this section:


Prerequisites


Setting Up the SMTP Server To Send E-Mail Notification

  1. In iManager, click Notification Configuration > Configure E-mail Server.

    The following page appears.


    Configure SMTP server interface
  2. Type the following information:

    • The host name
    • The name you want to appear in the From field of the e-mail message, such as Administrator
    • The username and password for authenticating to the server, if necessary.
  3. Click Close.

  4. If you are using Password Synchronization with your DirXML 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 the driver policies contain the password. See Providing SMTP Authentication Information in Driver Policies for instructions.

      Specifying the authentication information in the Configure E-Mail Server page in Step 2 is sufficient for Forgotten Password notifications, but not for Password Synchronization notifications.

    2. Restart DirXML 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.


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, click Notification Configuration > Modify E-mail Templates.

    A list of templates appears, like the following example.


    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 Adding Your Own Replacement Tags to E-Mail Notification Templates.

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

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


Providing SMTP Authentication Information in Driver Policies

You specify the username and password for the SMTP server in 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 DirXML engine can access the username, but not the password, so the driver policy must provide it.

You must complete this procedure if the following conditions exist:

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 Upgrading Existing Driver Configurations to Support Identity Manager Password Synchronization.

  2. In iManager, click DirXML Management > Overview. Search for the driver sets, or browse and select a container that holds the driver set.

    A graphical representation of the driver set appears.

  3. In the DirXML Overview, click the icon for the driver.

    A graphical representation of the driver configuration appears.

  4. 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 DirXML 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 eDirectory.


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.

In this section:


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 send notification to a user about a password synchronization failure. 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 DirXML 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 DirXML 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 eDirectory 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:

  1. Find all the policies that refer to the e-mail notification template.

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

  2. In each policy, edit each rule that refers to the template. In iManager, click DirXML Management > Overview. 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. 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.

    For example, if you were editing the Password(Pub)-Sub Email Notifications policy for the eDirectory driver, this is the page where you would click Edit:


    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 down to the section of the rules that displays the actions.

    For the example rule, you would scroll down to this 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. Note that 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 DirXML driver configurations, like this one. You can use the default tags as an example.


    String builder page
  9. Click Append New String to define a tag that you could use in an e-mail notification template. Enter a name for the tag, making sure it is exactly the same name you use in the e-mail notification template.

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

    The Argument Builder page appears. This is where you 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 eDirectory 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 shows an example of the page that helps you 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.

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

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

  13. 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.

  14. Save the changes and restart the driver.


Adding Replacement Tags to Forgotten Password E-Mail Notification Templates

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

  • 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 DirXML Driver for LDAP.

  • No other configuration is necessary.


Sending E-Mail Notifications to the Administrator

The default configuration is for the e-mail notification to go only to the user. The policies shipped with Identity Manager use the e-mail address from the eDirectory 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 DirXML 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, you need to 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. Here's an example of 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.


Localizing E-Mail Notification Templates

Keep in mind the following: