Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Identity Manager
11g Release 1 (11.1.1)

Part Number E14308-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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 via generation of errors. Event definition is the metadata that describes the event. To define metadata for events, it is important to identify all event types supported by a functional component. For example, as a part of the scheduler component, metadata can be defined for scheduled job execution failed and shutting down of the scheduler. Every time a job fails or the scheduler is shut down, the events are raised and notifications associated with that event are sent.

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 decide which event variables can be made available at 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, the only notification provider available is an e-mail notification provider. At the backend, the notification engine is responsible for generating the notification, and utilizing the notification provider to send the notification.

Note:

For sending notifications, the XL.MailServer system property must be configured. See "System Properties in Oracle Identity Manager" for information about this system property.

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 provide notification during a bulk request creation

Create User Self Service Notification

Template to provide notification after a new user is created

End Date

Template to provide notification to the manager when end date of the reportee expires

Generated Password Notification

Template to provide notification after a password is generated by Oracle Identity Manager

Request Creation

Template to provide notification during a request creation

Request Identity Creation

Template to provide notification during a Create User request

Request Status Change

Template to provide notification during a request status change

Reset Password

Template to provide notification after password has been reset

User Deleted

Template to provide notification to the manager when the user account of the reportee is deleted as a result of expired end date

Add Proxy Notification

Template to provide notification after a proxy has been added for a user


Notification templates are described in the following sections:

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>

The event XML file has the following elements:

Notification service reads the XML files from MDS. The event XML file is uploaded into MDS by using the MDS import and export utility. See "Deploying the Notification Event" for details.

3.1.1 Creating the Resolver Class

All classes have to implement the NotificationEventResolver interface. This interface provides the following methods:

The getAvailableData Method

public List<NotificationAttribute> getAvailableData(String eventType, Map<String, Object> params);

This API returns the list of available data variables. These variables are available on the UI while creating or modifying the templates and allows the user to select the variables so that they can be the part of the messages on the template.

The eventType parameter specifies the event name for which the template is to be read.

The params parameter is the map that has the entity name and the corresponding value for which available data is to be fetched. For instance:

map.put("Resource", "laptop");

This helps you fetch the fields associated with the laptop resource or other data according to the code that you have provided in the resolver class.

Sample code:

/**
* this is a dummy implementation and uses hardcoded values
* Implementors need to iterate the XML as found through the event type
* params : will have all the specific values that your resolver needs
* for instance resource name = "laptop" that you may want here to be resolved through your custon implementation
*/
 
List<NotificationAttribute> list = new ArrayList<NotificationAttribute>(); NotificationAttribute subatr = new NotificationAttribute(); subatr.setName("Dynamic1"); subatr.setType("91-Entity"); subatr.setEntityName("Resource"); subatr.setRequired(false); subatr.setSearchable(true); subatr.setSubtree(lookup91EntityMetaData("resource"), params.get(0)); list.add(subatr);

The main tree contains the entity information and the subtree contains all the nodes that are available on the UI. The name field from each node in the subtree is available on the UI for selection.

The getReplacedData Method

HashMap<String, String> getReplacedData(String eventType, Map<String, Object> params);

This API returns the resolved value of the variables present on the template at run time when notification is being sent.

The eventType parameter specifies the event name for which the template is to be read.

The params parameter is the map that has the base values, such as usr_key and obj_key, required by the resolver implementation to resolve the rest of the variables in the template.

Sample code:

HashMap<String, Object> resolvedData = new HashMap<String, Object>(); resolvedData.put("shortDate", new Date()); resolvedData.put("longDate", new Date());
String firstName = getUserFirstname(params.get("usr_key")); resolvedData.put("fname", firstName); resolvedData.put("lname", "lastname"); resolvedData.put("count", "1 million");
return resolvedData;

3.1.2 Deploying the Notification Event

To deploy the notification event:

  1. Upload the event metadata XML file to the Meta Data Store (MDS). Oracle Identity Manager provides utilities to export/import data to and from MDS repository.

    See "MDS Utilities and User Modifiable Metadata Files" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for information about the MDS utilities.

  2. Upload the JAR file containing the resolver class to Oracle Identity Manager database. Utilities are available in the OIM_HOME/bin/ directory for uploading resource bundles and JAR files to Oracle Identity Manager database.

    See "Upload JAR and Resource Bundle Utilities" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for information about the upload resource bundles and JAR utilities.

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. You must first configure the XML for an event. After this is done, 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:

  1. Log in to the Administrative and User Console. Navigate to Advanced Administration.

  2. Click the System Management tab, and then click the Notification tab.

  3. From the Actions menu on the left pane, select Create.

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

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

  6. 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 short version of the message.

    • In the Long Message field, enter the message that will be sent as the notification. See step 7.

  7. To use the token for available data in the messages that will be sent as notification:

    1. Select the attribute from the list. This attribute will be displayed in the Selected Data field.

    2. Copy the attribute and add it in the message text by placing it inside ${}. For example, if selected data is FA_Territory, then include it in the text as ${FA_Territory}.

    Figure 3-1 shows the Create Notification Template page with sample values:

    Figure 3-1 The Create Notification Template Page

    Description of Figure 3-1 follows
    Description of "Figure 3-1 The Create Notification Template Page"

  8. After you have entered the required values in all the fields, click Save.

  9. 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:

  1. Log in to the Oracle Identity Administration.

  2. Click the System Management tab and then click the Notification tab.

  3. Click the icon next to the Search field. All the existing notification templates are displayed on the left pane, as shown in Figure 3-2:

    Figure 3-2 Notification Search Result

    Description of Figure 3-2 follows
    Description of "Figure 3-2 Notification Search Result"

  4. 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:

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

    Figure 3-3 The Advanced Search Page

    Description of Figure 3-3 follows
    Description of "Figure 3-3 The Advanced Search Page"

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

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

  4. Click Search. The search results table is displayed with details about template names, event names, and subject details, as shown in Figure 3-4:

    Figure 3-4 Advanced Search Results

    Description of Figure 3-4 follows
    Description of "Figure 3-4 Advanced Search Results"

3.4 Modifying a Notification Template

To modify a notification template:

  1. Log in to the Oracle Identity Administration.

  2. Click the System Management tab and then click the Notification tab.

  3. 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-5 shows the details of a notification template.

    Figure 3-5 Notification Template Modification

    Description of Figure 3-5 follows
    Description of "Figure 3-5 Notification Template Modification"

  4. Change the values that you want to and click Save.

  5. A message is displayed confirming the modification of the notification template. Click OK.

3.5 Deleting a Notification Template

To delete a notification template:

  1. Log in to the Oracle Identity Administration.

  2. Click the System Management tab and then click the Notification tab.

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

  4. 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:

  1. Log in to the Oracle Identity Administration.

  2. Click the System Management tab and then click the Notification tab.

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

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

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

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

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

  3. 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:

  1. Configure a new Email IT resource.

  2. Create a new end user. (For example, create a user Jane Doe.)

  3. Create a second end user. (For example, create a user John Doe.)

  4. Assign the Jane Doe user as a manager for John Doe.

  5. Specify your email ID for John Doe, which enables you to receive notifications in your inbox.

  6. Log in as Jane Doe and navigate to the Oracle Identity Manager Self Service.

  7. Select Profile, Proxies. When the Proxies screen is displayed, add John Doe as a proxy for Jane Doe.

Note:

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

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