(English) Custom Event Handlers in OIM 11G-From OIM Dev Guide

Implementing Custom Event Handlers

To implement custom event handlers:

Implement one of the SPIs mentioned in table below to write a custom pre-process, post-process, or validation handler.

Table 7-3 SPIs to Write Custom Event Handlers

• Include the following JAR files in the class path to compile a custom class:
  From OIM_INSTALL_HOME/server/platform
• iam-platform-kernel.jar
• iam-platform-util.jar
• iam-platform-context.jar
• iam-plaftorm-authz-service.jar

From OIM_INSTALL_HOME/designconsole/lib

• OIMClient.jar
• xlAPI.jar

From OIM_INSTALL_HOME/designconsole/lib and OIM_INSTALL_HOME/server:
All other JAR files

• Create a library of JAR files containing the custom classes.

The following code samples illustrate how to invoke Oracle Identity Manager 9.1.x APIs and 11g APIs to customize user management operations. See SPI Javadocs for more information.

Example shows a sample custom validation handler code fragment that checks to ensure that $ is not used in a password.

throws ValidationException, ValidationFailedException {
    HashMap<String, Serializable> parameters = orchestration.getParameters();
    String password = (parameters.get("usr_password") instanceof ContextAware)
      ? (String) ((ContextAware) parameters.get("usr_password")).getObjectValue()
      : (String) parameters.get("usr_password");
    if (password.contains("$")) {
      throw new ValidationFailedException();
    }
}

Example 7-2 shows a sample custom pre process event handler code fragment that sets the middle initial to the first letter of the first name if the user does not have a middle name.

// This custom preprocess event handler sets the first letter of the first name as the middle initial
// when the user doesn't have a middle name
public EventResult execute(long processId, long eventId, Orchestration orchestration) {
   HashMap<String, Serializable> parameters = orchestration.getParameters();
   // If the middle name is empty set the first letter of the first name as the     middle initial
  String middleName = getParamaterValue(parameters, "Middle Name");
  if (isNullOrEmpty(middleName)) {
     String firstName = getParamaterValue(parameters, "First Name");
     middleName = firstName.substring(0,1);
     orchestration.addParameter("Middle Name", middleName);
  }
  return new EventResult();
}
private String getParamaterValue(HashMap<String, Serializable> parameters, String key) {
  String value = (parameters.get(key) instanceof ContextAware)
  ? (String) ((ContextAware) parameters.get(key)).getObjectValue()
  : (String) parameters.get(key);
  return value;
}

shows a sample custom post process event handler code fragment that provisions a resource object OBJ005 to a user whose role is ROLE 00.5

// This custom post process event handler provisions resource object 'OBJ005' to a user who has role 'ROLE 005'
public EventResult execute(long processId, long eventId, Orchestration orchestration) {
tcUserOperationsIntf userOperationsService = Platform.getService(tcUserOperationsIntf.class);
try {
String userKey = getUserKey(processId, orchestration);
if (hasRole(userKey, "ROLE 005")) {
long objKey = findObject("OBJ001");
userOperationsService.provisionResource(Long.getLong(userKey), objKey);
}
} catch (Exception e) {
throw new EventFailedException("Error occurred ", e);
}

return new EventResult();
}

// This method retrieves the key of the user entity on which an operation is performed
// This method shows how to retrieve the operation being performed, entity type
// and the associated value objects 
private String getUserKey (long processID, Orchestration orchestration) {
String userKey;
String entityType = orchestration.getTarget().getType();
EventResult result = new EventResult();

if (!orchestration.getOperation().equals("CREATE")) {
userKey = orchestration.getTarget().getEntityId();
} else {
OrchestrationEngine orchEngine = Platform.getService(OrchestrationEngine.class);
userKey = (String) orchEngine.getActionResult(processID);
}
return userKey;
}

// This method checks if a given user has a given role. 
// It demonstrates how to invoke a OIM 11g API from a custom event handler
private boolean hasRole(String userKey, String roleName) 
throws Exception {
RoleManager roleManager = Platform.getService(RoleManager.class);
List<Identity> roles = roleManager.getUserMemberships(userKey);

for (Iterator iterator = roles.iterator(); iterator.hasNext();) {
Role role = (Role) iterator.next();
if (roleName.equals((String)role.getAttribute("Role Name"))) {
return true;
}

}
return false;
}

// This method finds details about a resource object with the given name. 
// It demonstrates how to invoke a 9.1.x API from a custom event handler
private long findObject(String objName) throws Exception {
long objKey = 0;
tcObjectOperationsIntf objectOperationsService = Platform.getService(tcObjectOperationsIntf.class);
HashMap params = new HashMap();
params.put("Objects.Name", objName);
tcResultSet objects = objectOperationsService.findObjects(params);
for (int i = 0; i < objects.getRowCount(); i++) {
objects.goToRow(i);
if (objects.getStringValue("Objects.Name").equals(objName)) {
objKey = objects.getLongValue("Objects.Key");
}
}
return objKey;
}

Creating Plug-ins for Custom Event Handlers

To create plug-ins containing custom event handlers, you need to develop the appropriate event handler classes.

Note:
Ensure that plug-in point used in the plug-in definition is set to oracle.iam.platform.kernel.spi.EventHandler.

Note:
The plug-ins can be packaged as required, just like the JAR files, as long as they adhere to the packaging guidelines.

Here is an example of a plug-in XML file:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
  <plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">
    <plugin pluginclass=  
       "oracle.oim.extensions.preprocess.SamplePreprocessExtension" 
        version="1.0" 
        name="SamplePreprocessExtension">
    </plugin>
    <plugin pluginclass= 
        "oracle.oim.extensions.postprocess.SamplePostprocessExtension"
         version="1.0" 
         name="SamplePostprocessExtension">
    </plugin>
    <plugin pluginclass= 
       "oracle.oim.extensions.validation.SampleValidationExtension"
        version="1.0" 
        name="SampleValidationExtension">
    </plugin>
  </plugins>
</oimplugins>

7.2.2.3 Defining Custom Events

Take these steps to define custom events:

1. Create the metadata XML file containing definitions of all the custom events.
   Example 7-4 shows what a metadata file looks like:

<?xml version='1.0' encoding='utf-8'?>
<eventhandlers>
  <!-- Custom preprocess event handlers -->
  <action-handler

    entity-type="User" 
    operation="CREATE" 
    name="SamplePreprocessExtension"
    Stage="preprocess"
    order="1000" 
    sync="TRUE"/>

  <!-- Custom postprocess event handlers -->
  <action-handler

    entity-type="User" 
    operation="CREATE" 
    name="SamplePostprocessExtension"
    stage="postprocess"
    order="1000" 
    sync="TRUE"/>

  <action-handler

    entity-type="User" 
    operation="MODIFY" 
    name="SamplePostprocessExtension"
    stage="postprocess"
    order="1000" 
    sync="TRUE"/>

  <!-- Custom validation event handlers -->
   <validation-handler

    entity-type="User" 
    operation="CREATE" 
    name="SampleValidationExtension"
    order="1000"/>       

   <validation-handler

    entity-type="User" 
    operation="MODIFY" 
    name="SampleValidationExtension"
    order="1000"/>       
</eventhandlers>