Developing Notification Events

24 Developing Notification Events

For developing custom notification for various operations, the notification engine supports creation of notification events and notification templates.

This chapter describes how to develop notification events. It contains the following sections:

24.1 Notification Concepts

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.

Notification templates are associated to specific events. The templates are used for defining the format of the notification. Oracle Identity Manager provides predefined or default notification templates. In addition, you can create new notification templates.

For some events, Oracle Identity Manager sends notification by default. For example, when a user is created without username and password through UI or reconciliation, the login credentials are notified to the user and user's manager.

You can define new notification events by using notification APIs and resolver class, as described in the subsequent sections. The following are examples of custom notification requirements:

A user is assigned to a role. The user and role owner are to be notified.
A user is assigned with a new application instance, which is financially significant, as part of reconciliation. The application instance owner and compliance officer is to be notified for prospective rogue attempts.

24.2 Developing Custom Notification

Developing custom notification involves building the notification logic, creating the plug-in pack, building the invocation logic, and configuring the notification service.

This section describes how to develop custom notification. It contains the following topics:

24.2.1 Building the Notification Logic

Building the notification logic involves defining the event metadata XML and creating the Resolver class.

This section describes how to build the notification logic. It contains the following topics:

24.2.1.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 in Administering Oracle Identity Governance 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 in Administering Oracle Identity Governance.

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 custom event XML files from the META-INF directory of a plug-in.

The recommended way to use the event XML is by placing it in a plugin's META-INF directory. The structure of the custom notification event plug-in is:

The lib/ directory
- Notification_Resolver.jar
The META-INF directory
- Notification_Event.xml
plugin.xml

See Developing Plug-ins for detailed information about creating the plug-in JAR and deploying it by using the Plugin Registration Utility.

24.2.1.2 Creating the Resolver Class

All classes have to implement the NotificationEventResolver interface.

This section describes the methods of the NotificationEventResolver interface and provides an example of creating a custom resolver class. It contains the following topics:

Note:

To compile any custom notification event resolver class, the ORACLE_HOME/server/apps/oim.ear/APP-INF/lib/OIMServer.jar file must be included in the CLASSPATH.

24.2.1.2.1 The getAvailableData Method

The API is:

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.

24.2.1.2.2 The getReplacedData Method

The API is:

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;

24.2.1.2.3 Example: Creating a Custom Resolver Class

Consider the example of Oracle Identity Manager sending email notification to the user who has been added as a proxy. If the requirement is to change the date format in the notification email, then create a new resolver class file, such as AddProxyResolverModified, for notification while adding a proxy. The following is the code for the AddProxyResolverModified resolver class:

package oracle.iam.selfservice.notification;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Date;
import java.util.logging.Level;
import java.text.ParseException;
import java.text.SimpleDateFormat;
 
import static oracle.iam.identity.utils.Constants.PROXY_START_DATE;
import static oracle.iam.identity.utils.Constants.PROXY_END_DATE;
import static oracle.iam.identity.utils.Constants.PROXY_ORIGINAL_USR_NAME;
import static oracle.iam.identity.utils.Constants.PROXY_ORIG_USER_LOGIN;
import static oracle.iam.identity.utils.Constants.FIRSTNAME;
import static oracle.iam.identity.utils.Constants.LASTNAME;
import oracle.iam.notification.impl.NotificationEventResolver;
import oracle.iam.notification.vo.NotificationAttribute;
 
public class AddProxyResolverModified implements NotificationEventResolver {
public List<NotificationAttribute> getAvailableData(String eventType, Map<String, Object> params) throws Exception {
return null;
}
    
    public HashMap<String, Object> getReplacedData(String eventType, Map<String, Object> params)throws Exception {
 
        SimpleDateFormat sdfSource = new SimpleDateFormat("MMMMMMMM DD,yyyy HH:mm:ss a z");
        SimpleDateFormat sdfDestination = new SimpleDateFormat("EEE, d MMM yyyy HH:mm:ss Z");
        Date sdate = null;
        Date edate = null;

        HashMap<String, Object> resolvedData = new HashMap<String, Object>();
        resolvedData.put("firstName",params.get(FIRSTNAME));
        resolvedData.put("lastName",params.get(LASTNAME));
        resolvedData.put("originalusername",params.get(PROXY_ORIG_USER_LOGIN));


        String proxy_startDate = (String )params.get(PROXY_START_DATE);
        System.out.println("proxy_startDate : " + proxy_startDate);
        String proxy_endDate = (String)  params.get(PROXY_END_DATE);
        System.out.println("proxy_endDate : " + proxy_endDate);

        sdate = sdfSource.parse(proxy_startDate);
        edate = sdfSource.parse(proxy_endDate);


        proxy_startDate = sdfDestination.format(sdate);
        System.out.println("proxy_startDate : " + proxy_startDate);
        proxy_endDate = sdfDestination.format(edate);
        System.out.println("proxy_endDate : " + proxy_endDate);


        resolvedData.put("proxystartdate", proxy_startDate);
        resolvedData.put("proxyenddate", proxy_endDate);
        return resolvedData;
    }
}

24.2.1.3 Creating the plugin.xml File

The plugin.xml file is a standard XML file used by the plug-in framework. If any feature uses plug-ins, then it exposes a plug-in point. This XML has the information of plug-in point.

For notification event and resolver plug-in, the exposed plug-in point is:

oracle.iam.notification.impl.NotificationEventResolver

Sample plugin.xml for Notification event and resolver is:

<?xml version="1.0" encoding="UTF-8" ?> <oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<plugins pluginpoint="oracle.iam.notification.impl.NotificationEventResolver">
<plugin pluginclass="ext.domain.notification.resolver.SendChallengeQuestionsResolver" version="1.0" name="Challenge Question Resolver" /> </plugins>
</oimplugins>

24.2.2 Creating Plug-in Pack Containing the Resolver Class

After creating the Resolver class, you must package it into a plug-in JAR file, and deploy the JAR file by using the Plug-in Registration Utility.

See Developing Plug-ins for detailed information about creating the plug-in JAR and deploying it by using the Plugin Registration Utility.

24.2.3 Building the Invocation Logic

After building the notification logic by defining event metadata XML and creating the Resolver class, you can call the notification logic at a specific operation in Oracle Identity Manager. This is achieved by using event handlers.

The invocation logic for the notification is built as a custom event handler. The custom event handler is then configured at the right stage in the relevant operation. The custom event handler is then deployed by using the Plugin Registration Utility. See Developing Event Handlers for details about developing event handlers.

24.2.4 Configuring the Notification Service

Infrastructure-level configuration for notification can be done in Oracle Identity Manager or in BPEL workflow.

You have the following options for creating the infrastructure-level configuration for notification:

Notification Configuration in Oracle Identity Manager: In Oracle Identity Manager, notification configurations are handled via notification providers. UMS is the default notification provider. For information about notification providers, see Managing Notification Providers in Administering Oracle Identity Governance.
Notification Configuration in BPEL workflow: SOA exposes notification service, which can be called in BPEL workflow for notification. For information about SOA email notification, see Configuring SOA Email Notification in Administering Oracle Identity Governance.

Note:

Dynamic Monitoring Service (DMS) can be used to view performance metrics. The following DMS metrics are present for monitoring notification performance:

OIM_Notification: It provides the fine grained details about the time taken by the notification provider.
oracle.iam.notification.api.NotificationService: It provides details, such as the number of notifications and time taken by notification.