Tuesday Jun 17, 2014

Oracle Identity Manager Custom Event Handler

In an Identity Management system, any action performed by a user or system is called an operation. Examples of operations are creating users, modifying roles, and creating password policies. The process of any Oracle Identity Manager operation that goes through a predefined set of stages and executes some business logic in each stage is called an orchestration. The type of object that is changed by the orchestration is called an orchestration target. 

Orchestration is divided into predefined steps called stages. Every operation moves through these stages until it reaches finalization. Orchestration has the following stages:

  • Validation: Stage to perform validation on the orchestration, such as validity of orchestration parameters. Orchestration parameter is the data that is required to carry out the orchestration operation.
  • Preprocess: Stage to perform orchestration parameter manipulations or get approvals or perform Segregation of Duties (SoD) checks.
  • Action: Stage in which the action takes place.
  • Audit: Stage in which the auditing of operation is performed.
  • Postprocess: Stage in which consequent operations related to the current operation takes place. Examples of consequent operations are auto role membership and policy evaluation on a user creation.
  • Finalization: Last stage in the process to perform any clean up.

Oracle Identity Manager allows you to implement Service Provider Interfaces (SPIs) to customize the functionality of orchestration operations. Only customization of preprocess, postprocess, validation, and finalization stages of an operation in an entity orchestration is supported.

In my example, i will explain user enable operation. For example, we may want to change user's end-date when user's status change to enable.

1-) Develop custom event handler Java code.

For our example, I will use Postprocess stage therefore our class must be extended from oracle.iam.platform.kernel.spi.PostProcessHandler.

public class RoleUserEventManagement
  implements PostProcessHandler
private RoleUserEventProcessors roleUserEventProcessor;

  private RoleUserEventProcessors getRoleUserEventProcessor()
    if (this.roleUserEventProcessor == null) {
      this.roleUserEventProcessor = new RoleUserEventProcessors();

    return this.roleUserEventProcessor;

  public void initialize(HashMap<String, String> arg0)

  public boolean cancel(long arg0, long arg1, AbstractGenericOrchestration arg2)
    return false;

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

  public EventResult execute(long processId, long eventId, Orchestration orchestration)
    Utils.logger.error("[RoleUserEventManagement][execute] : Starting.");

    EventResult eventResult = new EventResult();
    String type = orchestration.getTarget().getType();
    Utils.logger.error("[RoleUserEventManagement][execute] type : " + type);

    if ("RoleUser".equalsIgnoreCase(type)) {
      try {
String operation = orchestration.getOperation();
             User user = getUserManager().getUser(processId, orchestration);
              if (UserManagerConstants.Operations.ENABLE.name().equalsIgnoreCase(operation)) {

      } catch (Exception e) {

    return eventResult;

  public BulkEventResult execute(long arg0, long arg1, BulkOrchestration arg2)
    return null;

2-) Create a jar.

Create a jar with custom event handler Java class. Jar must be include the following JAR files in the class path to compile a custom class:

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

3-)  Define a XML file.

<?xml version = '1.0' encoding = 'UTF-8'?>
<xl-ddm-data version="" user="XELSYSADM" database="jdbc:oracle:thin:@trkist01-odb-01:1521/MIDM" exported-date="1354621487559" description="RoleUserEventManagement">
     <eventhandlers repo-type="MDS" name="RoleUserEventManagement" mds-path="/db" mds-file="RoleUserEventManagement.xml">
               <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">
                    <action-handler orch-target="oracle.iam.platform.kernel.vo.EntityOrchestration" class="com.mypackage.oim.plugins.events.RoleUserEventManagement" entity-type="RoleUser" operation="CREATE" name="RoleUserEventManagement" stage="postprocess" sync="TRUE" order="FIRST" />

4-)  Create a plug-in zip file

  a.Define a plug-in XML.

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">
         <plugin pluginclass="com.mypackage.oim.plugins.events.RoleUserEventManagement" version="1.0" name="RoleUserEventManagement"/>

b.Package the plug-in XML and the JAR file that contains the custom class or classes into a plug-in ZIP file.

5-) Copy zip file to OIM_HOME/server/plugins directory.
6-) Register plug-in ZIP file.

You can use the Plugin Registration Utility for registering and unregistering plug-ins. The utility uses the following files:

  • pluginregistration.xml
  • ant.properties
These files are located in the OIM_HOME/plugin_utility/ directory.

Before using the utility, perform the following:

  1. Set the values for WLS_HOME and OIM_HOME in ant.properties.
  2. For example:

    WLS_HOME =.../middleware/wlserver_10.3

    OIM_HOME =..../middleware/Oracle_IDM1/server

    In addition, set the path for MW_HOME in the ant.properties file.

  3. Build the wlfullclient.jar in Oracle WebLogic server:
      1. Change directories to WLS_HOME/server/lib.
  4. Run the following command:
java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar

To register a plug-in:

  1. Execute the ant target "register":
  2. ant -f  pluginregistration.xml register
  3. This will prompt for the Oracle Identity Manager username and password along with the server information and the location of the plugin zip file. Enter the complete path of the zip file location.

About me:

Mustafa Kaya is a Senior Consultant in Oracle Fusion Middleware Team, living in Istanbul. Before coming to Oracle, he worked in teams developing web applications and backend services at a telco company. He is a Java technology enthusiast, software engineer and addicted to learn new technologies,develop new ideas.

Follow Mustafa on Twitter,Connect on LinkedIn, and visit his site for Oracle Fusion Middleware related tips.


Get the latest on all things Oracle PaaS and Fusion Middleware. Join Oracle's PaaS/Middleware Community today.

Find Us on facebook Follow us on twitter Catch Us on YouTube 


« July 2016