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

5.5.1 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 don'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 that 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 see the following 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 the value that 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.

5.5.2 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, refer to the Schema Mapping Policy that is provided in the Identity Manager Driver for LDAP.

  • No other configuration is necessary.

By default, the Forgotten Password E-Mail Notification template uses the UserFullName variable. The full name attribute is not used by the e-mail notification template, instead it uses the login attribute. For example, if the full name attribute is Alison Blake and the login attribute is ablake, the e-mail greeting is "Dear ablake" instead of "Dear Alison Blake".

The e-mail notification template uses the CN value of the variable found in the Identity Vault. For example, if cn=ablake, the e-mail notification template uses ablake. If the CN value is changed to Allison Blake, the e-mail notification template uses the full name, Allison Blake. If the FirstName variable is used instead of FullUserName variable, the e-mail notification template appears without the user's first name.