Tuesday, September 18, 2012

OIM 11g R2 UI customization

OIM 11g R2 new user interface is probably one of the most expected new features of this release. The main reason for that is the great customization capability provided by the underlying technologies: Oracle ADF and Oracle WebCenter Composer.

OIM user interface customizations are easier now, and they 'survive' patch applications (there is no need to reapply them after patching). Adding new artifacts,  new skins, and 'plugging' code directly into the user interface components became an easier task.

This post introduces some of the customization related concepts provided by the new OIM user interface.

ADF and WebCenter

The underlying technologies, Oracle ADF and Oracle WebCenter, provide a powerful customization framework for the brand new OIM user interface.

The OIM application now exposes user interface components through itself. It provides access to UI components details, so that one can modify them, and make the modifications available to other users. New UI components can easily be created and made available. Existing components can be easily hidden.

The picture below shows one UI component in 'edition mode':


A sandbox holds and isolates a set of UI customizations. The first customization step is to create a new sandbox and activate it. Then all customization work will be done in the context of the sandbox. Once the customization is tested and ready, the sandbox is published, and the customizations are made available to all users. A sandbox does not represent a UI component, or anything like that, it is a 'virtual entity' to hold customizations.

Sandboxes are not only used to customize the UI components, they are also used to create new forms (like an application instance Form) and edit the existing ones (like editing the User form to add UDFs). Sandboxes can be exported/imported in order to move customizations from one environment to another.

Behind the scenes, a sandobx is stored in the MDS database. Every time a user logs in into OIM, the UI verifies which customizations are available and apply them to the final rendered user interface.


Oracle ADF and Oracle WebCenter Composer bring the concept of 'expressions language' in OIM to a whole new level. Expressions can be used in different ways in the UI. They can be used to generate labels, invoke ADF managed beans, hide/show UI components, generate data, generate image links, and a lot of other cool and nice things.

Managed Beans

Managed beans are a piece of code that can be invoked from the OIM UI. Invoking a managed bean is done through the use of Expression Language.

OIM provides a pre-defined set of managed beans that can be invoked from ELs. These managed beans can be used to get useful information like the logged user details and request details. There is a list of pre-defined expressions that can be used to invoked these beans, such list is available here.

OIM also provides a WebLogic shared library that can be used to deploy custom managed beans. Such library is reference by OIM UI applications. The library can be located in the 'Deployments' page of the WebLogic management console. The library name is 'oracle.iam.ui.custom', and it points to the $OIM_ORACLE_HOME/sever/apps/oracle.iam.ui.custom-dev-starter-pack.war file. Deploying a managed bean is basically to add the managed bean jar file to this library; and update the library deployment in WebLogic.

But a managed bean is not a simple java code in a simple jar file, it has to follow the ADF development and deployment model. Therefore, JDeveloper is the required tool to code them. A new 'Fusion Web Application' is the start point for developing a managed bean:

The wizard will then create two projects: one for the 'View-Controller' code, and other for the 'Model' code. The 'View-Controller' project is most likely where the code will be done. Once the code is ready to be deployed, a deployment profile is needed:

When invoked, this deployment profile generates a Jar file wilt all artifacts and the custom code. This is the Jar file to be added to oracle.iam.ui.custom-dev-starter-pack.war, in the 'WEB-INF/lib' folder.

There are different ways a custom jar file can be added to the oracle.iam.ui.custom-dev-starter-pack.war library. The 'jar' command line is the first one to come to mind. But using a 'ZIP' tool (like 7-Zip, WinRAR or WinZIP) is easier because there is no need to worry about the 'META-INF' folder content (the contents in META-INF cannot be modified). While 'jar' needs parameter to not touch the 'META-INF' folder, a ZIP tool will not touch anything.


The OIM developer's guide has a lot of good information that go deeper in the concepts explained in this post. The documentation is available here.


  1. Hi, would you be able to comment on how to add a translation for a UDF added to the OIM user profile? The documentation is not clear on this. I have tried http://docs.oracle.com/cd/E27559_01/dev.1112/e27150/uicust.htm#autoId21 with no luck. There are various .properties files hanging around in the app but i'd rather not go on a wild goose chase. Also there is no admin.war so the method I found documented with R1 doesn't seem to apply either.


  2. Hi Daniel, could you also comment on how would one go about migrating UI customizations from one environment to another (say, QA to PROD)?

    1. Sandeep,

      That is a good idea for a post. Keep following the blog.

      Thank you


    2. I will say this is no small challenge. I have migrated a number of changes from my sandbox VM into a client's DEV environment, and will be migrating those changes plus many many more into the client's TEST environment soon. Best advice I can give is (1) Name your sandboxes with Client_yyyyMMdd_HHmm so that each sandbox is basically date stamped by its name and is nearly impossible to accidently create a second time (a big no-no) (2) Always export your sandbox before publishing (3) Be meticulous (borderline psychotic) about documenting everything you do and (4) always follow the published documentation on migration.

  3. Is a sandbox a container for customizations made since the sandbox was created? So it's only a container for incremental changes rather than all customizations made to date?

    1. You can create multiple sandboxes. But you can only have *one* sandbox active at a time. So whatever modifications/customizations you do will be at stored in the sandbox that is 'active' at the customization time.

    2. And by that logic they are incremental.

    3. So is it a best practice to never commit your sandbox in a dev environment? it looks like once committed, it's no longer a sandbox, and no longer exportable. I'd prefer maintain all my cumulative customizations in a single deployment package, rather than accruing multiple deployment packages that must be applied one at a time to a new target environment.

    4. Jeremy,

      No, it is not a best practice to never commit. It is true you cannot export it after you commit, so you have to export it before.

      But you should always commit the sandbox so it gets tested by the end users/testers. When you create a sandbox, you usually do that as system administrator, and first test it that way, but that is not a complete test case, the users to whom the functionality is meant to need to test it as well.

      Keep in mind that sandboxes are not only used for UI customization, they are also used in some OIM functionalities like UDF and application instance forms. And for being able to use these ones you have to publish the sandbox.

  4. Anyone who can answer this question. I have a USR_UDF_LASTUPDATEDDATE which is a date field in the USR table and comes from my custom connector through a Trusted Source Reconciliation. I am able to verify it is in the database. When I customize the "View User Details" page (see page 7-23 of the e27149 Administrators Guide) and add that field to the page, it shows up blank. I have tried this with a ADF Output Text w/Label and an ADF Output Formatted w/Label. Neither works and none of the other dates show up. How do I get these dates to show on the page?

    1. Keith,

      I tested in my environment and the date shows up fine in the View User Details page. I used ADF Output Text with Label.

      make sure the data component you are selecting for this specific page is "Data Component - Manage Users" and not the "Data Component - Catalog"


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