3 Managing Notification
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.
This chapter describes event metadata, notification configuration, and notification templates 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:
-
EventType name: The name of the event that will be available while creating notification templates for the event.
-
StaticData: The list of static parameters. This set of parameters specifically let the user add parameters that are not data dependent. In other words, this element defines the static data to be displayed when notification template is to be configured. For instance, the user entity is not data dependent, and when resolved, has the same set of attributes for all the event instances and notification templates.
-
Param DataType: The list of dynamic parameters. This set of parameters specifically let the user add parameters that are data dependent. For instance, the Resource entity is data dependent. Corresponding to this field, a lookup is displayed on the UI. When the user selects the resource object, the call goes to the Resolver class provided to get the fields that are shown in the tree 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. See step 7 of "Creating a Notification Template" for an example of a token.
Available data is displayed in a drop-down list while creating a notification template, as described in "Creating a Notification Template".
Selected data is a single attribute that helps user to copy and paste the attribute name in a notification template. 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.
Note:
The <Param DataType> element is not a mandatory element. However, when it is used, the entity names must be specified as User, Resource, or Organization.
-
Resolver class: 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 "Creating the Resolver Class" for information about implementing the resolver class.
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:
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.
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:
-
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.
-
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 Configuring UMS for Notification
User Messaging Service (UMS) is the default notification provider in Oracle Identity Manager. The following procedure describes how to configure user login or password email notifications through UMS framework:
-
Configure the 'Email Provider Instance - UMS' IT resource values with UMS web service details. To do so:
-
Login to the Administrative and User Console, and then click Advanced.
-
In the Welcome page, under Configuration, click Manage Resource.
Alternatively, click the Configuration tab, click Resource Management, and then select Manage Resource.
The Resource Search page is displayed.
-
Search for the 'Email Provider Instance - UMS' IT resource. Click the Edit icon for the IT resource, and select Details and Parameters from the list at the top of the page.
-
Edit the values of the following IT resource parameters:
-
Username: Username given in the security header. This user must exist at server side, which is UMS server. If no policy is attached, then leave it as blank.
-
Password: Password given in the security header. This user must exist at server side, which is UMS server. If no policy is attached, then leave it as blank.
-
Web service URL: The URL of the UMS web service to be invoked in the following format:
http://HOST_NAME:PORT_NUMBER/ucs/messaging/webservice
-
Policies: If any server side OWSM Policy is attached to the given web service for security, then provide the name of the corresponding client side OWSM policy here. Otherwise, leave it as blank. For example, if 'oracle/wss11_username_token_with_message_protection_service_policy' is applied at server level, then provide the corresponding client policy name as 'oracle/wss11_username_token_with_message_protection_client_policy'.
-
-
Click Update to save the changes.
-
-
By default, Linux mail server is picked at server side to send emails. If you want to change the default mail server, then configure a specific email server. This step is not required if you want the local Linux mail server to be used for sending notifications.
To configure UMS server to use any specific email server:
-
Stop the Linux local sendmail email server in the host computer if it is a Linux host.
-
Log in to Oracle Enterprise Manager.
-
Go to User Messaging Service, usermessagingdriver-email (soa_server1), Email Driver Properties in Driver-Specific Configuration.
-
Configure the following (mandatory):
-
OutgoingMailServer: The name of the SMTP server. This is required for sending emails.
-
OutgoingMailServerPort: The port number of the SMTP server. For example, 465 for SSL outgoing mail server and 25 for non-SSL.
-
OutgoingMailServerSecurity: The security setting used by the SMTP server. Possible values can be None, TLS, or SSL.
-
OutgoingUsername: Any valid username. A sample username is oim-email_us@mycompany.com.
-
OutgoingPassword: This consists of three fields:
Type of Password: Select Indirect Password, Create New User. You can select other options based on security requirements. For details about other options, see "Securing Passwords" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process.
Indirect Username/Key: Provide a unique string, for example, OIMEmailConfig. This masks the password and does not expose it in cleartext in the config file.
Password: Provide a valid password for this account.
-
-
Click Apply.
-
Right-click usermessagingdriver-email (soa_server1), and select Control, Shutdown.
-
Allow at least 120 seconds after which you can restart the email driver. Right-click usermessagingdriver-email (soa_server1), and select Control, Restart. For more information, see "Configuring the Email Driver" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process.
-
(Optional) If mail server security is SSL, then perform the additional step to remove DemoTrust store references from the SOA environment. To do so:
i) Modify the $INSTALL_HOME/user_projects/domains/$DOMAIN_HOME/bin/setDomainEnv.sh or appropriate Windows cmd file to remove the DemoTrust references, as shown:
-Djavax.net.ssl.trustStore=$WL_HOME/server/lib/DemoTrust.jks from EXTRA_JAVA_PROPERTIESii) Open and edit startManagedWeblogic.sh or cmd file in Windows. Remove the following weblogic.security.SSL.trustedCAKeyStore property set in JAVA_OPTIONS from the following file:
JAVA_OPTIONS="-Dweblogic.security.SSL.trustedCAKeyStore="{MW_HOME}/server/server/lib/cacerts" ${JAVA_OPTIONS}"iii) Restart the Admin and Managed Servers.
Note:
For detailed information on how to view log, message status, and email driver settings, see "Configuring Oracle User Messaging Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
-
-
Secure the web service with OWSM policy by applying server side policy on UMS web service and providing policy details in IT resource at client side. To do so:
-
In Oracle Enterprise Manager, expand User Messaging Service, and click usermessagingserver (soa_server).
-
From the User Messaging Service list, select Web Services.
-
In the Web Service Details section, click the Web Service Endpoints tab.
-
In the Endpoint Name column, click Messaging.
-
Click the OWSM Policies tab.
-
Under Directly Attached Policies, click Attach/Detach. A list of available policies and the options to attach and detach policies are displayed.
-
Select a policy from the available policies list, and click Attach. The selected policy is added to the Directly Attached Policies list.
The policy you select is for securing the Messaging UMS web service.
-
To validate the applied policy combination, refresh the page. A message is displayed stating that the validation is successful.
-
Click OK.
-
To provide policy-specific values at client side:
i) Edit the IT Resource Type for adding new field as KeyStore Alias. For this, Login to the Design Console. Go to Resource Management, IT Resource Type Definition, Email Provider Definition - UMS.
ii) Add a new field named Keystore Alias, and save.
Note:
keystoreAlias is the keystore alias for the target service. Sample value can be xeltrusted.
iii) Configure the IT resource values, as shown in step 1.
Tip:
UMS is the default notification provider. But if you want to switch from UMS notification provider to SMTP notification provider, then change the same in NotificationConfig tag of the oim-config.xml file. MBean is exposed for oim-config.xml. This can be done by using Oracle Enterprise Manager as shown:
-
Login to Oracle Enterprise Manager.
-
Go to Identity and Access, oim, oim(11.1.1.x.x). Right-click and navigate to System MBean Browser.
-
Click Attribute EmailProvider, and replace "oracle.iam.notification.provider.UMSEmailServiceProvider" with "oracle.iam.notification.provider.EmailServiceProvider".
-
Click Apply.
-
3.3 Managing Notification Templates
This section contains the following topics:
3.3.1 Default Notification Templates
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 |
3.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:
-
Log in to the Administrative and User Console. Navigate to Advanced Administration.
-
Click the System Management tab, and then click the Notification tab.
-
From the Actions menu 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 short version of the message.
-
In the Long Message field, enter the message that will be sent as the notification. See step 7.
-
-
To use the token for available data in the messages that will be sent as notification:
-
Select the attribute from the list. This attribute will be displayed in the Selected Data field.
-
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 The Create Notification Template Page"
-
-
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.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-2:
-
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-3:
-
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-4:
3.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-5 shows the details of a notification template.
Figure 3-5 Notification Template Modification
Description of "Figure 3-5 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.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.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.4 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 user Jane Doe.)
-
Create a second end user. (For example, create a user John Doe.)
-
Assign the Jane Doe user as a manager for John Doe.
-
Specify your email ID for John Doe, which enables you to receive notifications in your inbox.
-
Log in as Jane Doe and navigate to the Oracle Identity Manager Self Service.
-
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".
3.5 Troubleshooting Notification
After you configure notification, you can test the configuration by using the Notification Configuration Test available in the Diagnostic Dashboard. To do so, provide a valid user login as parameter for this test from the Diagnostic Dashboard console.
A dummy user creation mail is sent if a valid email ID exists for the login provided, and the result of the test will be similar to Figure 3-6.
Figure 3-6 Notification Configuration Test
Description of "Figure 3-6 Notification Configuration Test"
Figure 3-7 shows a failed Notification Configuration Test.
Figure 3-7 Failed Notification Configuration Test
Description of "Figure 3-7 Failed Notification Configuration Test"