Developing and Deploying Event Handlers in OIM 11G R2

In this post, we set the middle name as “MiddleName” if user does not provide middle name during user create operation.

Below are high-level steps:

1. Environment Setup
2. Developing plugins
1. Creating a JAR file with Custom Event Handler code
2. Creating Plugin XML
3. Creating Event Handler XML
4. Creating a Plug-in ZIP
3. Registering the Plug-in
1. Run the below script to register plugin in OIM server
2. Importing the Custom Event into MDS Schema
3. Clear the OIM Cache
4. Clear the OIM Cache 
4. Testing the Event handlers

Environment Setup

The following jar files are required to compile the event handler code: 

From the OIM_ORACLE_HOME/server/platform/ directory:

•         iam-platform-kernel.jar

•         iam-platform-utils.jar

•         iam-platform-context.jar

•         iam-plaftorm-authz-service.jar

From the OIM_ORACLE_HOME/designconsole/lib/ directory:

•         oimclient.jar

•         xlAPI.jar

Developing Plugins

Creating a JAR file with Custom Event Handler code

This below java code will set hard coded middle name as “MiddleName”.

package com.oimacademy.eventhandlers;

import java.util.HashMap;

import com.thortech.util.logging.Logger;

import oracle.iam.platform.kernel.spi.PreProcessHandler;

import oracle.iam.platform.kernel.vo.AbstractGenericOrchestration;

import oracle.iam.platform.kernel.vo.BulkEventResult;

import oracle.iam.platform.kernel.vo.BulkOrchestration;

import oracle.iam.platform.kernel.vo.EventResult;

import oracle.iam.platform.kernel.vo.Orchestration;

public class MiddleNameExtension implements PreProcessHandler {

private Logger logger = Logger.getLogger("com.oimacademy.eventhandlers.MiddleNameExtension");

  @Override

 public void initialize(HashMap<string, string> arg0) {

  // TODO Auto-generated method stub

 }

 @Override

 public boolean cancel(long arg0, long arg1, AbstractGenericOrchestration arg2) {

  return false;

 }

 @Override

 public void compensate(long arg0, long arg1, AbstractGenericOrchestration arg2) {

  // TODO Auto-generated method stub

 }

 @Override

 public EventResult execute(long processId, long eventId, Orchestration orch) {

  // Request parameters from the OIM form

  HashMap parameters = orch.getParameters();

  // Type of operation like CREATE, DELETE, etc.,

  String operation = orch.getOperation();

  if (operation != null && operation.equalsIgnoreCase("CREATE")) {

   if (!parameters.containsKey("Middle Name")) {

    orch.addParameter("Middle Name", "MiddleName");

   }

  }

  return new EventResult();

 }

 @Override

 public BulkEventResult execute(long processId, long eventId, BulkOrchestration bulkOrch) {

  return null;

 }

}

Make JAR file using below command or you can use tools such as eclipse, jdev, etc.,

<span lang="EN" style="font-family: Arial, sans-serif;">jar cvf MiddleNameExtension.jar * </span>
jar cvf MiddleNameExtension.jar *

Creating Plugin XML

Define the plug-in XML with the event handler plug-in point.

<?xml version="1.0" encoding="UTF-8"?>

<oimplugins>

  <plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">

    <plugin pluginclass="com.oimacademy.eventhandlers.MiddleNameExtension"
version="1.0" name="MiddleNameExtension" />

  </plugins>

</oimplugins>

Save this file as plugin.xml

Creating Event Handler XML

<?xml version='1.0' encoding='utf-8'?>

<eventhandlers xmlns="http://www.oracle.com/schema/oim/platform/kernel/"

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.oracle.com/schema/oim/platform/kernel orchestration-handlers.xsd">

   <!-- Custom preprocess event handlers for middlename -->

   <action-handler class="com.oimacademy.eventhandlers.MiddleNameExtension" entity-type="User"
operation="CREATE" name="MiddleNameExtension" stage="preprocess" order="FIRST" sync="TRUE"/>

</eventhandlers> 

Save this file as MiddleNameExtension.xml 

In OIM 11GR1, we import this xml in to OIM using weblogicImportMetadata.xml.

In OIM 11GR2, we can keep this in META-INF folder of Plugin-in zip.

Note: All event handlers must have valid XML name space. If you give wrong name spaces, OIM Orchestration engine will not recognize as event handler and as result, plugin won’t be triggered.

Creating a Plug-in ZIP

Plug-in zip structure:

Package plug-in XML (plugins.xml), the JAR (lib/MiddleNameExtension.jar), and Event handler XML (META-INF/MiddleNameExtension.xml) as zip file.

Register the Plug-ins zip into the OIM Server 

We need to set below environment variables before running the script.

export APP_SERVER=weblogic

export ANT_HOME=/app/Middleware/modules/org.apache.ant_1.7.1

export JAVA_HOME=/app/Middleware/jdk160_29

export PATH=/app/Middleware/jdk160_29/bin:/app/Middleware/modules/org.apache.ant_1.7.1/bin:$PATH

export MW_HOME=/app/Middleware

export WL_HOME=/app/Middleware/wlserver_10.3

export DOMAIN_HOME=/app/Middleware/user_projects/domains/iam_domain

Run the below script to register plugin in OIM server: 

ant -f pluginregistration.xml register 

It will ask the following details after running the above command
1. OIM Admin User Name: xelsysadm
2. OIM Admin Password: password
3. OIM T3 URL: t3://localhost:14000

4. Context Factory: weblogic.jndi.WLInitialContextFactory (if its weblogic)

5. Plugin zip file location: Provide absolute path

Plugin (Event hanlder) will installed successfully without any issues. Some time it will show throw error if the class file is not found in the jar file

Importing the Custom Event into MDS Schema

Go to the OIM_HOME/bin directory and modify the following properties in the weblogic.properties file

wls_servername=oim_server1
application_name=OIMMetadata
metadata_from_loc=/home/oracle/eventhandlers

Event Handler Config file location as /home/oracle/eventhandlers/metadata/EventHandlers.xml

Run the weblogicImportmetada.sh file and will ask the following details

1) Weblogic Admin User Name : weblogic
2) Weblogic Admin Password : weblogic admin password
3) weblogic Admin URL : t3://localhost:7001

After running the above command the custom scheduler task will be imported into the MDS Schema.

Clear the OIM Cache

After we installed the plugin, we need to run Purge Cache utility to clear  and reload the plugin.

Run the PurgeCache.sh All file and it will ask the following details.
1. OIM Admin User Name: xelsysadm
2. OIM Admin Password: password
3. OIM T3 URL: t3://localhost:14000

After running the above command and it will clear the OIM cache

Restart the OIM Server

Go to the WL_DOMAIN_HOME/bin direcory and run stopManagedServer.sh oim_server1 command and it will stop the oim managed server.

Run the startManagedServer.sh oim_server1 and it will start the OIM Managed Server.

Testing The Event Handlers 

Login to the OIM Identity Console >> Users >> Create User >> Enter User’s First Name, Last Name, Login ID, Password, Organization Name, User Type and Click Save Button. It will display user created successfully as well, Middle Name as “MiddleName”