Developing and Deploying Event Handlers in OIM 11G R2

In this post, we set the middle name as “MN” 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
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 “MN”.

package blog.chella;

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("blog.chella.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", "MN");
   }
  }
  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.,

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="blog.chella.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="blog.chella.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.

Regsiter 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=/opt/middleware/modules/org.apache.ant_1.7.1
export JAVA_HOME=/opt/java/jdk1.7.0_02
export PATH=/opt/java/jdk1.7.0_02/bin:/opt/middleware/modules/org.apache.ant_1.7.1/bin:$PATH
export MW_HOME=/opt/middleware
export WL_HOME=/opt/middleware/wlserver_10.3
export DOMAIN_HOME=/opt/middleware/user_projects/domains/base_domain

Run the below script to register plugin:

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.

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

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 “MN”