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() {}
}
