OIM
11g has introduced an improved and template based
Notifications framework. New release has removed the limitation of sending text
based emails (out-of-the-box emails) and enhanced to support html features. New
release provides in-built out-of-the-box templates for events like 'Reset
Password', 'Create User Self Service' , ‘User Deleted' etc. Also provides new
APIs to support custom templates to send notifications out of OIM.
OIM
notification framework supports notification mechanism based on events,
notification templates and template resolver. They are defined as
follows:
Ø Events
are defined as XML file and imported as part of MDS
database in order to make
notification event available for use.
Ø Notification
templates are created using OIM advance administration console. The template
contains the text and the substitution 'variables' which will be replaced with
the data provided by the template resolver. Templates support
internationalization and can be defined as HTML or
in form of simple text.
Ø Template
resolver is a Java class that is responsible to provide attributes and data to
be used at runtime and design time. It must be deployed following the OIM
plug-in framework. Resolver data provided at design time is to be used by end
user to design notification template with available entity variables and it also
provides data at runtime to replace the designed variable with value to be
displayed to recipients.
Steps
to define custom notifications
in OIM 11g are:
Steps#
Steps
1.
Define
the Notification Event
2.
Create
the Custom Template Resolver class
3.
Create
Template with notification contents to be sent to
recipients
4.
Create
Event triggering spots
in OIM
1. Notification
Event metadata
The
Notification Event is defined as XML file which need to be imported into MDS
database. 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.XSD location
in MDS database:
“/metadata/iam-features-notification/NotificationEvent.xsd”Schema
file can be viewed by exporting file from MDS using
weblogicExportMetadata.sh script.Sample Notification event metadata
definition:
1: <?xml version="1.0"
encoding="UTF-8"?>
2:
<Events xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:noNamespaceSchemaLocation="../../../metadata/NotificationEvent.xsd">
3: <EventType
name="Sample Notification">
4:
<StaticData>
5:
<Attribute
DataType="X2-Entity" EntityName="User" Name="Granted
User"/>
6: </StaticData>
7: <Resolver class="com.iam.oim.demo.notification.DemoNotificationResolver">
8: <Param DataType="91-Entity" EntityName="Resource" Name="ResourceInfo"/>
9: </Resolver>
10: </EventType>
11:
</Events>
Line#
Description
1.
XML
file notation tag
2.
Events
is root tag
3.
EventType tag is to declare a unique event name which
will be available for template designing
4.
The
StaticData
element lists a set of parameters which allow user to 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. Available
attributes are used to be defined as substitution tokens
in the template.
5.
Attribute
tag is child tag for StaticData to declare the entity
and its data type with unique reference name. User entity is most commonly used
Entity as StaticData.
6.
StaticData
closing tag
7.
Resolver
tag defines the 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. Resolver class resolves the data dynamically at run time and
displays the attributes
in the UI.
8.
The
Param DataType element
lists a set of parameters which allow user to add parameters that are data
dependent. An example of the data dependent or a dynamic entity is a resource
object which 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 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.
Param
tag is child tag to declare the entity and its data type with unique reference
name.
9.
Resolver
closing tag
10
EventType
closing tag
11.
Events
closing tag
Note: - DataType needs to be declared as “X2-Entity” for User entity
and “91-Entity” for Resource or Organization entities. The dynamic entities
supported for lookup are user, resource, and
organization.
Once
notification event metadata is defined, need to be imported into MDS
database.
Fully qualified resolver class name need to be define for XML but do not need to
load the class
in OIM yet (it can be loaded later).
2. Coding
the notification resolver
All
event owners have to provide a resolver class which would resolve the data
dynamically at run time. Custom resolver class must implement the interface
oracle.iam.notification.impl.NotificationEventResolver
and override the implemented methods with actual implementation. It has 2
methods:
S#
Methods
Descriptions
1.
public
List<NotificationAttribute> getAvailableData(String eventType,
Map<String, Object> params);
This
API will return the list of available data variables. These variables will be
available on the UI while creating/modifying the Templates and would let user
select the variables so that they can be embedded as a token as part of the
Messages on the template. These
tokens are replaced by the value passed by the resolver class at run time.
Available data is displayed
in a list.
The
parameter "eventType" specifies the event Name for
which template is to be read.The parameter "params" is the map which has the entity name and the
corresponding value for which available data is to be
fetched.
Sample
code snippet:
List<NotificationAttribute> list = new ArrayList<NotificationAttribute>();
long
objKey = (Long) params.get("resource");
//Form
Field details based on Resource object key
HashMap<String,
Object> formFieldDetail = getObjectFormName(objKey);
for
(Iterator<?> itrd =
formFieldDetail.entrySet().iterator(); itrd.hasNext(); )
{
NotificationAttribute availableData = new NotificationAttribute();
Map.Entry formDetailEntrySet = (Entry<?, ?>)itrd.next();
String
fieldLabel = (String)formDetailEntrySet.getValue();
availableData.setName(fieldLabel);
list.add(availableData);
}
return
list;
2.
Public
HashMap<String, Object> getReplacedData(String eventType,
Map<String, Object> params);
This
API would return the resolved value of the variables present on the template at
the runtime when notification is being sent.
The
parameter "eventType" specifies the event Name for
which template is to be read.The parameter "params" is the map which has the base values such as usr_key, obj_key etc required by
the resolver implementation to resolve the rest of the variables
in the
template.
Sample
code snippet:
HashMap<String, Object> resolvedData = new HashMap<String, Object>();String firstName = getUserFirstname(params.get("usr_key"));resolvedData.put("fname", firstName);
String
lastName = getUserLastName(params.get("usr_key"));resolvedData.put("lname", lastname);resolvedData.put("count", "1 million");return resolvedData;
This
code must be deployed as per OIM 11g plug-in framework. The XML file defining
the plug-in is as 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.iam.oim.demo.notification.DemoNotificationResolver"
version="1.0" name="Sample Notification Resolver"/>
</plugins>
</oimplugins>
3. Defining
the template
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: Demo template
Description Text: Demo template
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. Note that the template
Sample Notification Event created
in the previous step being used as the
notification event. The contents of the Available Data drop down are based on
the event XML StaticData tag, the drop down basically
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 prefixing $ symbol. Example if list has attribute like First_Name then message body will contains this as $First_Name which resolver will parse and replace it with
actual value at runtime.
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. Based on selected
resource getAvailableData method of resolver will be
called to fetch the resource object attribute detail, if method is overridden
with required implementation. For current scenario, Map<String, Object>
params will get populated with object key as value and
key as “resource”
in the map. This is the only input will be provided to
resolver at design time. You need to implement the further logic to fetch the
object attributes detail to populate the available Data list. List string should
not have space
in between, if object attributes has space for attribute name
then implement logic to replace the space with ‘_’ before populating the list.
Example if attribute name is “First Name” then make it “First_Name” and populate the list. Space is not supported
while you try to parse and replace the token at run time with real
value.
Make
a note 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.
Under
the Locale Information section, enter values
in the following
fields:
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
with Available data token which need to be replaced by resolver at
runtime.
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
4. Triggering
the event
A
notification event can be triggered from different places
in OIM. The logic
behind the triggering must be coded and plugged into OIM.
Examples
of triggering points for 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
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
Sample
Code Snippet:
public
void execute(String templateName , String userId) {
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= { poUserId
};
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() {}
}
