3 Managing Notification Templates

Information about events occurring in Oracle Identity Manager are required to be sent to various users, such as requesters, beneficiaries, or administrators. This information about events is sent by using the notification service in the form of notification e-mail messages. The notification service allows you to perform all notification-related operations in Oracle Identity Manager.

An event is an operation that occurs in Oracle Identity Manager, such as user creation, request initiation, or any custom event created by the user. The events are generated as part of business operations or generation of errors. Event definition is the metadata that describes the event. Metadata for events are provided by identifying all event types supported by a functional component. For example, as a part of the scheduler component, metadata can be defined for schedule job execution failed and shutting down of the scheduler. Every time a job fails or the scheduler is shut down, the events are raised.

The data available in the event is used to create the content of the notification. The different parameters defined for an event help the system to select the appropriate notification template. The different parameters that are defined for an event help the system to decide what all event variables can be made available at the template design time.

A notification template is used to send notifications. These templates contain variables that refer to available data to provide more context to the notifications. The channel through which a notification is sent is known as the notification provider. For this release, only e-mail is available as the notification provider. At the backend, the notification engine is responsible for generating the notification, and utilizing the notification provider to send the notification.

Note:

An IT resource of name Email Server and type Mail Server must be configured for sending notifications. The email server settings gets cached. If there is a change in detail of an already configured email server, then you must restart the application server or delete the cache, as required.

Oracle Identity Manager provides a set of default notification templates, as shown in Table 3-1.

Table 3-1 Default Notification Templates

Notification Template	Description
Bulk Request Creation	Template to notify during a bulk parent request creation
Create User Self Service Notification	Template to notify after a new user is created
End Date	Template to notify the manager when end date of the reportee expires
Generated Password Notification	Template to notify after a password is generated by Oracle Identity Manager
Request Creation	Template to notify during a request creation
Request Identity Creation	Template to notify during a Create User request
Request Status Change	Template to notify during a request status change
Reset Password	Template to notify after password has been reset
User Deleted	Template to notify the manager when the user account of the reportee is deleted as a result of expired end date
Add Proxy Notification	Template to notify after a proxy has been added for a user

Notification templates are described in the following sections:

Defining Event Metadata
Creating a Notification Template
Searching for a Notification Template
Modifying a Notification Template
Deleting a Notification Template
Adding and Removing Locales from a Notification Template
Configuring Notification for a Proxy

3.1 Defining Event Metadata

Corresponding to each event, you must create an XML file that has the specific schema defined by the notification engine. Compliant to that schema (.xsd file), an XML file is created that defines how an event looks like. When the event is defined, you can configure a notification template for that event.

An event file must be compliant with the schema defined by the notification engine, which is NotificationEvent.xsd. The event file contains basic information about the event.

Note:

The NotificationEvent.xsd file is in the iam\iam-product\features\notification\metadata directory in the MDS.

The following is a sample event XML file:

<?xml version="1.0" encoding="UTF-8"?>
<Events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../metadata/NotificationEvent.xsd">
  <EventType name="User Created">
    <StaticData>
      <Attribute DataType="X2-Entity" EntityName="User" Name="Granted User"/>
      <Attribute DataType="X2-Entity" EntityName="User" Name="Grantee User"/>
      <Attribute DataType="91-Entity" EntityName="User Group" Name="User Grp"/>
    </StaticData>
      <Resolver class="oracle.iam.notification.DemoResolver">
      <Param DataType="91-Entity" EntityName="Resource" Name="ResourceInfo"/>
    </Resolver>
  </EventType>
</Events>

In the sample XML file:

The EventType name element is the name of the event.
The StaticData element lists a set of parameters that lets the user add parameters that are not data dependent. In other words, this element defines the static data to be displayed when notification is to be configured. An example of static data is the user entity, which is not dependent on any other data and has the same set of attributes for all event instances and notification templates.
The Param DataType element lists a set of parameters lets the user add parameters that are data dependent. An example of the data dependent or a dynamic entity is a resource object that the user can select at run time. A notification template is to be configured for the resource object. Corresponding to the resource object field, a lookup is displayed on the UI. When a user selects the event, for example End Date Notification, the call goes to the Resolver class provided to fetch the fields that are displayed in the Available Data list, from which user can select the attribute to be used on the template.

Note:
Available data is the list of attributes that can be embedded as a token in the template. These tokens are replaced by the value passed by the resolver class at run time. Available data is displayed in a list.
Selected data is a single attribute that helps user to copy and paste the attribute name. Selected data is the same attribute name as selected in the Available Data list.

The dynamic entities supported for lookup are user, resource, and organization. These entity names must be specified in the Param DataType element.
The Resolver class must be defined for each notification. It defines what parameters are available in the notification creation screen and how those parameters are replaced when the notification is to be sent. In other words, the resolver class resolves the data dynamically at run time and displays the attributes in the UI.

See Also:
"Notification Tab" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for more information about the resolver class and the methods supported by the resolver class

The event XML file is uploaded into MDS by using the MDS import and export utility. Notification service reads the XML files from MDS.

3.2 Creating a Notification Template

Note:

Corresponding to each event that happens, you have to configure an XML file. The XML file defines the behavior of each event. Only after an XML is configured for an event, you can create a notification template for that event.

For information about creating the event XML file, see "Defining Event Metadata".

To create a notification template:

Log in to the Oracle Identity Administration.
Click the System Management tab and then click the Notification tab.
From the Actions list on the left pane, select Create.
On the Create page, enter values for the following fields under the Template Information section:
- Template Name: Enter the template name in this field.
- Description Text: Enter a brief description of the template in this field.
  
  Note:
  The Description Text field cannot be translated and is available only in English.
Under the Event Details section, perform the following:
- From the Available Event list, select the event for which the notification template is to be created from a list of available events. Depending on your selection, other fields are displayed in the Event Details section.
- In the Resource field, select a resource from the lookup. This is the dynamic data defined by the Param DataType element in the XML definition. For more information about this element, see "Defining Event Metadata".
Under the Locale Information section, enter values in the following fields:

Note:
The Default Locale information is stored in the PTY table and is fetched from there.
- To specify a form of encoding, select either UTF-8 or ASCII.
- In the Message Subject field, enter a subject for the notification.
- From the Type options, select the data type in which you want to send the message. You can choose between HTML and Text/Plain.
- In the Short Message field, enter a gist of the message in very few words.
- In the Long Message field, enter the message that will be sent as the notification. See step 7.
To consume token in available data inside the messages that will be sent as notification:
1. Select the attribute from the list. This attribute will get displayed in the Selected Data field.
2. Copy the attribute and consume it in message text by placing it inside ${}. For example, if selected data is FA_Territory, then include it in text the as ${FA_Territory}.
After you have entered the required values in all the fields, click Save.
A message is displayed confirming the creation of the notification template. Click OK.

3.3 Searching for a Notification Template

You can perform a simple search or an advanced search for a notification template by using Advanced Administration.

To perform a simple search for a notification template:

Log in to the Oracle Identity Administration.
Click the System Management tab and then click the Notification tab.
Click the icon next to the Search field. All the existing notification templates are displayed on the left pane, as shown in Figure 3-1:

Figure 3-1 Notification Search Result

Description of "Figure 3-1 Notification Search Result"
Select the template that you want to view. The details of the selected notification template are displayed on the right pane.

To perform an advanced search for a notification template:

In the left pane of the Oracle Identity Administration, click Advanced Search. The Advanced Search page is displayed, as shown in Figure 3-2:

Figure 3-2 The Advanced Search Page

Description of "Figure 3-2 The Advanced Search Page"
Select one of the following matching options:
- All: On selecting this option, the search is performed with the AND condition. This means that the search operation is successful based on Search field with any input from the user. Search field with no input from the user is not considered.
- Any: On selecting this option, the search is performed with the OR condition. This means that the search operation is successful when any search criterion specified is matched.
Specify the search criteria in the Template Name, Event Name, and Subject Details fields. You can remove any of these fields that you do not want to include in the search by clicking the icon next to it. You can add a field that you want to include in the search by clicking Add Fields, and then selecting the field name from the list.
Click Search. The search results table is displayed with details about template names, event names, and subject details, as shown in Figure 3-3:

Figure 3-3 Advanced Search Results

Description of "Figure 3-3 Advanced Search Results"

3.4 Modifying a Notification Template

To modify a notification template:

Log in to the Oracle Identity Administration.
Click the System Management tab and then click the Notification tab.
Click the icon next to the Search field. All the existing notification templates are displayed on the left pane. Select the template that you want to modify. Figure 3-4 shows the details of a notification template.

Figure 3-4 Notification Template Modification

Description of "Figure 3-4 Notification Template Modification"
Change the values that you want to and click Save.
A message is displayed confirming the modification of the notification template. Click OK.

3.5 Deleting a Notification Template

To delete a notification template:

Log in to the Oracle Identity Administration.
Click the System Management tab and then click the Notification tab.
Click the icon next to the Search field. All the existing notification templates are displayed on the left pane. Select the template that you want to delete.
From the Actions list, click Delete. A message is displayed prompting you to confirm the delete the operation. Click OK. A message is displayed confirming the delete operation.

3.6 Adding and Removing Locales from a Notification Template

To add locales to a notification template:

Log in to the Oracle Identity Administration.
Click the System Management tab and then click the Notification tab.
Click the icon next to the Search field. All the existing notification templates are displayed on the left pane. Select the template that you want to add a locale to.
From the Actions list, select Add Locale. The Add Locale page is displayed. In the Locale Name field, click the icon next to the Locale Name field to select a locale from a list. After selecting the locale, click Confirm. Click Next. The Locale Information page is displayed and the locale that you added is displayed as a tab in the page.
In the Locale Information section, specify values for all the fields as mentioned in step 6 of "Creating a Notification Template" and then click Save. The locale is added to the template.

Note:
Notification can be sent in all the locales that are added to the notification template. A user receives notification in the same locale specified in the user preferences. If a locale is not specified in the user preferences, then the notification is sent in the default locale. The default locale is to be specified in the PTY table in Oracle Identity Manager database at the time of installation.

To remove locales from a notification template:

In the left pane of the Oracle Identity Administration, select the template from the search results table, and click Remove Locale from the Actions list. Alternatively, you can right-click the template, and select Remove Locale.
On the Remove Locale page, click the icon next to the Locale Name field to select a locale from a list . Remember, you can remove a locale from a template only if that template contains multiple locales. You cannot remove a locale if it's the only one associated with the template. Click Save.
A message is displayed confirming the removal of the locale. Click OK.

Note:
You must not remove default locale to ensure that a notification is sent every time when there is no user preferred locale is set or when notification template does not contain a locale template matching to user preferred locale.

3.7 Configuring Notification for a Proxy

Use the following steps to configure notification for a proxy:

Configure a new Email IT resource.
Create a new end user. (For example, create a "test1" user.)
Create a second end user. (For example, create a "test2" user.)
Assign the test1 user as a manager for the test2 user.
Specify your email ID for the test2 user, which enables you to

receive notifications in your inbox.
Log in as test1 and navigate to the Oracle Identity Manager Self Service.
Select Profile, Proxies, and when the Proxies screen is displayed,

add test2 as a proxy for the test1 user.

Note:

If you successfully added the proxy, you (the test2 user in this case) will receive an email notification message similar to the following:

"You have been made the proxy for test1 test1[TEST1] from April 7, 2010 12:00:00 AM to April 30, 2010 12:00:00 AM".