OIM 11g Notifications

Notifications are one of the multiple features that were improved in OIM 11g release. The previous limitation of sending text based emails (out-of-the-box emails) only is gone.

Out-of-the-box templates for events like 'Reset Password', 'Create User Self Servic', 'User Deleted' are available and custom templates can be defined and used to send notifications out of OIM.

OIM provides a notification framework based on events, notification templates and template resolver. They are defined as follows:

• Events are defined in a XML file and must be loaded into MDS database in order to be available for use.
• Notification templates are defined through OIM advance administration console. The template contains the text and the substitution 'variables' that will be substituted by the data provided by the template resolver. Templates support HTML and text based emails and multiple languages.
• Template resolver is a Java class that is responsible for providing the data to be used to parse the template, it must be deployed as an OIM plugin. The data provided by the resolver class will be used by OIM in the template substitution variables.

The main steps for defining custom notifications in OIM are:

1. Define the Event that will be used for triggering the notification
2. Define the Template to be formatted and sent
3. Create the Template Resolver class
4. Trigger the event from the relevant spot in OIM

This post explain each of the steps above and give some tips on how to create the notifications.



1. Defining the Event and its metadata

The Notification Event is defined through a XML file that must be loaded into MDS database. Also in MDS, there is a XSD that defines the tags and properties that the event XML may contain. The XSD is available at the following location in the MDS database:

/metadata/iam-features-notification/NotificationEvent.xsd

You can use the weblogicExportMetadata.sh script to export the XSD file.

Below an example of an event metadata definition:

<?xml version="1.0" encoding="UTF-8"?>
<Events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../metadata/NotificationEvent.xsd">
  <EventType name="Demo Notification Event">
    <StaticData>
      <Attribute DataType="X2-Entity" EntityName="User" Name="User Login"/>
	  <Attribute DataType="91-Entity" EntityName="User Group" Name="User Grp"/>
    </StaticData>
     <Resolver class="com.oracle.demo.oim.notification.DemoNotificationEventResolver">
      <Param DataType="X2-Entity" EntityName="User" Name="usr_login"/>
    </Resolver>
  </EventType>
</Events>

The property name in the tag EventType defines the event name, this is used in the OIM advanced administration UI. The StaticData session defines the entities (and their attributes) that can be used in the notification template, the entities attributes are used to define substitution tokens in the template. The resolver tag defines the Java class that OIM will invoke to provide the data to be used in the notification and the parameters that must be provided to the resolver class.

The XML must be loaded into the MDS database using the weblogicImportMetadata.sh script. You need to define resolver class name, but you don't need the class loaded in OIM just yet (it can be loaded later).

2. Defining the template

With the notification event defined in OIM, it is time to create the notification template based on that event. This action is done from the OIM advanced administration UI. The image below depicts the template created for this post:

Note that the template Demo Notification Event created in the previous step being used as the notification event.

Also note the Available Data dropdown and the Selected Data text field. The contents of the drop down are based on the event XML StaticData tag, the drop down basicly lists all the attributes of the entities defined in that tag. Once you select an element in the drop down, it will show up in the Selected Data text field and then you can just copy it and paste it into either the message subject or the message body fields. The picture below depicts this action:

It is important to mention that the Available Data and Selected Data are used in the substitution tokens definition only, they do not define the final data that will be sent in the notification. OIM will invoke the resolver class to get the data and make the substitutions.

3. Coding the notification resolver

The template resolver must implement the interface oracle.iam.notification.impl.NotificationEventResolver and provide actual implementation for the methods defined in the interface.

package com.oracle.demo.oim.notification;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import oracle.iam.identity.usermgmt.api.UserManager;
import oracle.iam.identity.vo.Identity;
import oracle.iam.notification.api.NotificationService;
import oracle.iam.notification.impl.NotificationEventResolver;
import oracle.iam.notification.vo.NotificationAttribute;
import oracle.iam.platform.Platform;

public class DemoNotificationEventResolver implements NotificationEventResolver{
    
    public DemoNotificationEventResolver() {}

   }
    public List<NotificationAttribute> getAvailableData(String eventType, Map<String, Object> map) {
        
        List<NotificationAttribute> list = 
new ArrayList<NotificationAttribute>();
        return list;
    }

    public HashMap<String, Object> getReplacedData(String eventType, Map<String, Object> eventParams) throws Exception {
        

        HashMap<String, Object> resolvedNotificationData = new HashMap<String, Object>();
        
        UserManager usrMgr = Platform.getService(UserManager.class);
        
        //getting the notfication parameter
        String userLogin = (String) eventParams.get("user_login");
        
        // Mapping token with their actual value for user attributes.
        if (userLogin != null) {
          
            NotificationService notificationService =  Platform.getService(NotificationService.class);
            //getting the list of all possible notification attributes
            List<NotificationAttribute> notificationAttributes =  notificationService.getStaticData(eventType);
            
            //seting the attributes for user search based on the notification attributes
            Set<String> userRetAttrs = new HashSet<String>();
            for (NotificationAttribute notificationAttribute :  notificationAttributes.get(0).getSubtree()) {
                userRetAttrs.add(notificationAttribute.getName());
            }
            
            //searching the user
            Identity user = usrMgr.getDetails(userLogin, userRetAttrs ,true);
            HashMap<String, Object> userAttributes = user.getAttributes();
            
            //setting the values in the resolved notification data Map
            String key = null;
            for (Map.Entry<String, Object>  entry : userAttributes.entrySet()) {
                
                key = entry.getKey();
                
                if (key != null) {
                    if ((entry.getValue() instanceof java.util.Map) && (key.equalsIgnoreCase(""))) {
                        key = key.replace(' ', '_');
                        resolvedNotificationData.put(key,  ((HashMap)entry.getValue()).get(""));
                    } 
                    else {
                        key = key.replace(' ', '_');
                        resolvedNotificationData.put(key, entry.getValue());
                    }
                }
           }
        }
        //returning the resolved data with all user information
        return resolvedNotificationData;
    }

This code must be deployed as an OIM plugin. The XML file defining the plugin is available below:

<?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= "com.oracle.demo.oim.notification.DemoNotificationEventResolver" version="1.0" name="Demo Event Resolver"/>     
    </plugins>
</oimplugins>

4. Triggering the event

A notification event can be triggered from different spots in OIM. The logic behind the triggering must be coded and plugged into OIM. Some examples of spots for triggering notifications:

• Event handlers: post process notifications for specific data updates in OIM users
• Process tasks: to notify the users that a provisioning task was executed by OIM
• Scheduled tasks: to notify something related to the task

In this post, a scheduled job was used to trigger the event. The scheduled job has two parameters:

• Template Name: defines the notification template to be sent
• User Login: defines the user record that will provide the data to be sent in the notification

 The scheduled job code:

package com.oracle.demo.oim.schedule;

import java.util.HashMap;

import oracle.iam.notification.api.NotificationService;
import oracle.iam.notification.vo.NotificationEvent;
import oracle.iam.platform.Platform;
import oracle.iam.scheduler.vo.TaskSupport;

public class NotificationDemoScheduledTask extends TaskSupport {
    
    public NotificationDemoScheduledTask() {
        super();
    }

    public void execute(HashMap taskParameters) {
  
        String templateName = (String)taskParameters.get("Template Name");
        String userId = (String)taskParameters.get("User Login");
        
        try {
            
            NotificationService notService = Platform.getService(NotificationService.class);
            NotificationEvent eventToSend = this.createNotificationEvent(templateName,userId);
            notService.notify(eventToSend);
            
        } catch (Exception e) {
            e.printStackTrace();
        }         
    }

    private NotificationEvent createNotificationEvent(String poTemplateName, String poUserId) {
        
        NotificationEvent event = new NotificationEvent();
        
        String[] receiverUserIds= {"xelsysadm"};       
        event.setUserIds(receiverUserIds);
        
        event.setTemplateName(poTemplateName);
        
        event.setSender(null);
        
        HashMap<String, Object> templateParams = new HashMap<String, Object>();
        templateParams.put("USER_LOGIN",poUserId);

        event.setParams(templateParams);
        
        return event;
    }

    public HashMap getAttributes() {
        return null;
    }

    public void setAttributes() {}
}

The XML below that defines the scheduled task plugin:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <plugins pluginpoint="oracle.iam.scheduler.vo.TaskSupport">
        <plugin pluginclass= "com.oracle.demo.oim.schedule.NotificationDemoScheduledTask" version="1.0" name="Notification Demo Task"/>     
    </plugins>
</oimplugins>

The XML below defines the scheduled task in OIM:

<?xml version='1.0' encoding='UTF-8'?>
<scheduledTasks xmlns="http://xmlns.oracle.com">
  <task>
    <name>Notification Task</name>
    <class>com.oracle.demo.oim.scheduled.NotificationDemoScheduledTask</class>
    <description>Notification Demo Task</description>
    <retry>5</retry>
    <parameters>
      <string-param required="true" helpText="Notification Template Name">Template Name</string-param>
    </parameters>
   </task>
</scheduledTasks>

5. Final comments

• You should be able to easily deploy the samples above and get the custom OIM notification example working
• Don't forget to configure the Email Server IT Resource instance in OIM. This configuration is required to send out  emails
• If you develop from a Windows based laptop/desktop, you can install the Test Mail Server Tool. Then configure OIM Email Server IT Resource instance to point to it and it will show the notifications.

This post is part of the OIM 11g Academy. Check here for other OIM 11g posts.