Monday, June 13, 2011

OIM 11g Event Handlers

Event Handlers are among the most common customizations in OIM 11g implementations. They have been available in OIM for a long time, but with 11g and its new frameworks, they certainly are becoming even more popular.

The most common use of event handlers is for extending the user management operations. Although a variety of business requirements can be achieved through custom event handlers, they must be used with care and with focus on the performance impact they may bring to OIM transactions.

The main types of Event Handlers are:

  • Pre-Process: triggered BEFORE the actual transaction is executed
  • Post-Process: triggered AFTER the actual transaction is executed, but within the transaction
  • Validation: triggered BEFORE the actual transaction starts and can prevent the transaction from happening if the validation fails
Because they are executed after the actual transaction happens, the post-process event handlers are asynchronous to the main transaction. In other words, they do not impact the main transaction performance.
But keep in mind that they can and will affect OIM overall performance, they are just another code to be executed by the application server.
Event Handlers are tied to specific entities in OIM like ‘Users’ and ‘Groups’. They are also tied to specific transactions, like ‘CREATE’, ‘MODIFY’ or ‘DELETE’, and they can also be tied to any transaction.
In OIM 11g, the Event Handlers are implemented through the plugin framework. An Event Handler comprises of:
  • The XML file that defines the event handler and specifies (among other things): Event Handler name, Java class with the implementation, entity type, the stage that the event handler will be executed (preprocess, postprocess) and other information depending on the type
  • The plugin that contains the code to be executed
Finally getting to the point: a list of recommendations that should be considered in Event Handlers implementation.

  •  Use OIM 11APIs whenever possible; avoid using ‘Thor.API.tcUserOperationsIntf for searching users. Make use of the new APIs like ‘oracle.iam.identity.usermgmt.api.UserManager’ and ‘oracle.iam.identity.usermgmt.vo.User’APIs like
  • Use the class ‘oracle.iam.platform.Platform’ to get instances of the APIs. When this class is used, there is no need for API authentication. The instances returned run under ‘internal’ user in OIM, therefore the update operations can be done without authenticating: Platform.getService(UserManager.class)
  • Avoid long running operations in Event Handlers. Even if the code can be executed as post process asynchronous operation, think about moving any long running operation to scheduled tasks and/or other OIM features
  • Use ‘oracle.iam.platform.entitymgr.EntityManager’ for updating user attributes. This will prevent OIM from triggering the event handlers once again
  • Avoid things like accessing external database (or other database schemas), reading files and other ‘external to OIM’ operations. They will slow down the event handler execution.
  • Do not forget that OIM invokes the event handlers in two different ways: bulk and non-bulk. Make sure that your Event Handler code is smart enough to handle both situations.
  • OIM instantiates one instance of each event handler during application server startup and keeps invoking it. Take this into consideration when designing and implementing your Event Handler.
The recommendations above may or may not apply to your business cases and implementation, but they are a good start point when designing Event Handler implementations.

Check the Oracle Identity Manager Academy for other OIM 11g related posts


  1. Hi,
    We used Use ‘oracle.iam.platform.entitymgr.EntityManager’ and we are getting problems with updated value being triggered via triggers lookup and now supports says you should not use EntityManager as its undocumented API and rather than user UserManager

  2. As stated in the blog post, using the 'EntityManager' API will prevent OIM from triggering event handlers once again. 'EntityManager' API bypasses the orchestration framework (hence the event handlers are not invoked), that is the reason you do not see the updated value being triggered.


Note: Only a member of this blog may post a comment.