OIM 11g R2 UI Customization Tips and Tricks

Introduction

OIM 11g R2 has finally provided OIM Developers with the means to implement very sophisticated and functional rich customizations to the Out of the Box User Interface of OIM; and the best part is, all these customizations are patching and upgrade transparent, which means that when the OIM installation is upgraded or patched, the customizations don’t have to be re-applied. Everything is stored in the metadata repository (MDS) and it is applied on top of the standard user interface. This article presents a few techniques to implement customizations that go a little beyond the capabilities of Web Composer; but still are within the scope of OIM’s MDS. Each technique will be presented in the context of a use case addressed by the customization implemented using the given technique.

On a recent post by Daniel Gralewski, there was a very nice customization for the Catalog. The purpose of such customization was to filter the resources already provisioned to a user from the results of a catalog search. In a follow up question, one of our readers asked if the search screen could be customized to add a drop down box that can be used to trigger a predefined search, like a catalog search based on role category.

So I thought that would be a nice use case to start, here is what I envisioned based on certain requirements from an actual customer I am helping at the present time.

According to the requirements users can request resources and application roles by Organization, but there is a set of applications that are available regardless of the user’s organization.

So the Catalog UI will have the following elements:

• An initial drop down box which displays all the applications available to the currently logged in user (Enterprise Applications plus the ones published to the user’s Organization). This list is compiled by executing a couple of searches that are structured in different ways. The Resource Hierarchy will be explained later along with how it is setup in OIM.

• A second drop down box which will display the list of Application Modules associated to the selected Application from the first drop down box. If the selected Application doesn’t have any modules or has only one, this second drop down box is not displayed at all. The requirement in this case is to directly display the application roles associated to the only module of the selected application or to the application itself. So behind the scenes, the proper searches are built and executed.

The configuration

To make these customizations possible we needed to define a resource hierarchy that ties together the cascading catalog searches that will be created dynamically and invoked to populate each drop down box and resource table downstream. The way this works is by tagging the catalog items in a way that expresses the relationship between items (i.e. Application Modules tied to Applications and Application Roles ties to Modules). So below is an example of such tagging conventions:

• Application Customer Channel (CCH)
• Application Modules
• Online Billing (OLB)
• Admin Agent Role (AAR)
• Audit Agent Role (AUAR)
• Promotion Agent Role (PAR)
• Customer Support (CSUPP)
• Support Agent Role (SAR)
• Support Manager Role (SMR)
• Products and Services (PANDS)
• User Role (USRR)
• Admin Role (ADMR)
• Marketing (MKT)
• Campaign Manager Role (CMGR)
• Product Manager Role (PMGR)

Applications are categorized as: 

• Enterprise Application (Tagged as: EnterpriseApp)

• Organization Application (Tagged as: OrgApplication).

• Application Modules are tagged as AppModule.

• Application Roles are tagged as AppRole.

The following table shows the Resource Hierarchy for the Application shown above:

Resource Name	Category	Tags
Customer Channel	ApplicationInstance	OrgApplication
Online Billing	ApplicationInstance	AppModule, CCH, OLB
Customer Support	ApplicationInstance	AppModule, CCH, CSUPP
Products and Services	ApplicationInstance	AppModule, CCH, PANDS
Marketing	ApplicationInstance	AppModule, CCH, MKT
Admin Agent Role	Role	AppRole, OLB
Audit Agent Role	Role	AppRole, OLB
Promotion Agent Role	Role	AppRole, OLB
User Role	Role	AppRole, PANDS
Admin Role	Role	AppRole, PANDS
Support Agent Role	Role	AppRole, CSUPP
Support Manager Role	Role	AppRole, CSUPP
Campaign Manager Role	Role	AppRole, MKT
Product Manager Role	Role	AppRole, MKT

Based on the Tagging and Categorization shown above the following search can be used to retrieve the Organization Applications available to the logged in user’s organization:

Fig 1-1 Tagging conventions for Catalog Searches of Organization Applications.

The results are placed in a List variable called orgApplications. Now in order to display them in the first drop down box the following code creates the list of SelectItem elements for the drop down box. 

Fig. 1-2 Organization Applications results processing logic.

Then I will show you how to connect that to the actual drop down box on the screen. As you can see in the code fragment above, the SelectItem instances are built with the Catalog Entity Display Name as the SelectItem’s label and the EntityName as the value. The following table lists the entity names of the ApplicationInstances defined in this example:

Entity Name	Entity Display Name	Category
CCH	Customer Channel	ApplicationInstance (OrgApplication)
OLB	On Line Billing	ApplicationInstance (AppModule)
CSUPP	Customer Support	ApplicationInstance (AppModule)
PANDS	Products and Services	ApplicationInstance (AppModule)
MKT	Marketing	ApplicationInstance (AppModule)

Now, how do we get these Application Instances to show up in the Drop Down boxes for user selection? Here is how:

• If you haven’t logged in to the Identity Self Service console, please do so.

• Once there, create a Sandbox, if not already, and activate it.

• Go to the Catalog screen by clicking on the Catalog link from the left side menu.

• Click Customize and select ‘Source’ view.

• Now you need to add the Drop Down box to the screen. Here is what I did in my case (yours might be different):

Fig 1-3 Adding a Single Selection Drop down menu to the search page of the Catalog Taskflow.

Notice that I selected a panelGroupLayout which is the container of the original input text box used to perform searches in the catalog (I didn’t remove it, just hid it by checking off the Visible attribute of the inputText component in Composer – that’s why it is not rendered here). 

By clicking the Add Content button, while inside the container shown above, the drop down box will be added as the top child component in that container; all that is needed now is to move it down the list of Child Components as shown below:

Fig 1-4 Reordering functionality in Web Composer

Notice the ‘Available Applications’ child component (This is the drop down box on the screen above) which was moved below the Magnifying Glass icon.

The selectOneChoice component that represents the Drop Down box, has a child component of type ‘UISelectItems’ (This was added to the drop down box just as the drop down box was added to its container – via the Add Content button). This is important because here is where the actual items list will be attached, following is how:

The Web Composer doesn’t allow manipulating the UISelectItems properties, so what we need to do is to export the sand box after these components were added to the screen and edit the metadata file presented to you below:

Listing 1-1: Contents of the searchcatalog.jsff.xml file.

In the figure above, the modifications you need to make are in the value property of the f:selectItems tag. As you can see, I set it to #{CatalogTFManager.filterBox1List}. Look at the figure below to see where this is defined:

Fig. 1-5 Filter Box 1 Component Binding member variable declaration.

Previously I showed you how the filterBox1List gets populated with the OrgApplications, but this box also include Enterprise Applications. Below is the code that populates both lists:

Fig. 1-6 Constructor initialization logic for LOVs in Catalog Search and Results pages

Another thing to notice from the sand box export shown in listing 1-1 is the valueChangeListener property which is set to: #{CatalogTFManager.selectedApplicationChanged}. This method, previously mentioned, populates the selections on the second drop down box that gets its values from filterBox2List shown above right below filterBox1List’s declaration. The filterBox2List is used to populate the second drop down box added to the container in the same way as the first drop down box and is configured as shown in listing 1-1.

The f:selectItems tag of the second drop down box also has a valueChangedListener which will populate the list of Catalog Items that are displayed in the results table on the next page of the Task Flow, which is called catalogResult.jsff. The listing below shows the most relevant contents of this metadata file:

Listing 1-2: Relevant contents of catalogResult.jsff.xml file.

As you can see above we also added the two drop down boxes as the ones in the previous page just to keep a consistent UI across both screens (you might want to implement everything on one screen if you so desire, nothing prevents you from doing so). Also notice the configuration changes for the table “t1” and the original input text field for catalog searches “it1”. The reason why we preserved the it1 is to leverage the button that triggers the final search for the Catalog items that need to be displayed on the table in the second page of the task flow, this button triggers navigation to the second page of the task flow for Catalog Requests and it is only enabled when something has been entered in the expression inputText field (it1). So we are leveraging the actual out of the box navigation mechanisms. Another important piece is the selectionListener of the t1 table which is overridden by my own listener. The reason for this is because the elements in the table are represented by a wrapper class that encapsulates catalog items. This wrapper class is a decorator that adds functionality to the catalog item it contains so an appropriate icon that represents the Catalog Item’s Entity Type is displayed. I don’t have access to this wrapper class, it is internal to OIM’s UI Beans and the OOTB selection listener works with instances of this class and expects the rows of the table to be instances of the wrapper class. So I had no choice but override the selection listener to work with mere catalog items (Catalog class instances). You may want to create your own Catalog items Wrapper Class.

This should give you an idea of how the cascading searches were implemented for this use case.

Summary

Here is the list of steps to implement this customization:

• Create a Sandbox and activate it.
• Open the Catalog page and do the following:
• Add two SelectOneChoice components to the page with their corresponding SelectItems subcomponent.
• Remove the Visible flag from the InputText field for the search expression (this is part of the out of the box interface)
• Create the Managed Beans for the logic of the Catalog screen and deploy your library. These beans will be responsible for:
• Execute the required Catalog Searches.
• Creating Lists of Values (Initially or based on selections from other list boxes).
• Respond to UI events like selection changes or button clicks.
• After the library has been successfully deployed, add bindings to the UI components (via composer) to tie the UI components on both pages of the Catalog Task Flow to member variables in the Managed Beans. This is required to control how UI components will be rendered according to the application’s state (like enabling/disabling buttons or links, or extracting the current multiple selections from the search results table).
• Publish your Sandbox and test.

This article is part of the OIM 11g Academy Series.