Oracle Identity Manager: Add Custom ADF Tabs in the Self Service Console

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

This tutorial is an expanded example that is based on the Oracle Identity Manager 11g Developers Guide chapter, which describes how to add a custom ADF tab to the Self Service console. The customization support enables complex customizations in the Self Service. You can add additional top-level tabs to the right of the Tasks, Requests, and Profile sections of the Self Service console.

The expanded example shows you how to create a simple user profile page using standard ADF functionality with the data for the currently logged in user.

Time to Complete

Approximately 1 hour.

Overview

The objective of this tutorial is to provide the steps to create a custom top level tab in the Self Service console of Oracle Identity Manager 11g. The custom tab you create is added at the end of the four top levels tabs (Welcome, Tasks, Requests, Profile) that are displayed when you visit the Self Service console page after signing into the Oracle Identity Manager 11g administration console. The following image showing the default tabs displayed in the Oracle Identity Manager Self - Service page:

Note: Before you start, you can sign into the Oracle Identity Manager administration console, and navigate to the "Oracle Identity Manager - Self Service" page to view the default list of tabs before you make any customizations.

In addition to creating one or more custom tabs by using Oracle's ADF UI technology, customization scenario for the top level tabs includes support for hiding one or more of the default tabs.

Scenario (Optional)

None.

Software and Hardware Requirements (Optional)

The following is a list of software requirements used in this tutorial:

Prerequisites

Before starting this tutorial, you should have installed, configured, and started:

.

The Oracle Database

.

The Oracle WebLogic Server

.

Oracle Identity Manager

The Sample Project

The example described here is also included as a sample JDeveloper project. This project can be used as a starting point for other ADF custom tab development. By using the sample CustomTabs project you generate an ADF jar file, called adflibCustomTabs1.jar, which is copied into $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF/lib directory, followed by additional configuration changes that are needed to expose the functionality through a custom tab.

Note: First, download the Custom Tabs Zip file into your home directory or a folder of your choice.

This tutorial provides instructions for using the downloaded file, such as where to unzip the contents of the zip file and how to use the extracted contents of the zip file, which contains the CustomTabs.jpr JDeveloper project and its associated source files.

About Project Library Dependencies

After you open the CustomTabs.jpr project in JDeveloper you need to configure the library path dependencies, in the project properties, based on your system configuration and environment for libraries listed in the following table:

Table of Library Dependencies
Library File Directory/Location
iam-features-identity.zip $MW_HOME/Oracle_IDM1/server/features
iam-platform-entitymgr.jar $MW_HOME/Oracle_IDM1/server/platform
iam-platform-utils.jar $MW_HOME/Oracle_IDM1/server/platform
iam-platform-context.jar $MW_HOME/Oracle_IDM1/server/platform
iam-features-selfservice.zip $MW_HOME/Oracle_IDM1/server/features
iam-platform-authz-service.jar $MW_HOME/Oracle_IDM1/server/platform

This table can be used as a reference for locating paths to the library files, even though the tutorial provides instructions for configuring the library paths.

Note: In the Table of Library Dependencies, the Middleware home is indicated by the presence of the $MW_HOME environment variable, which must be altered to suit your development and runtime environment. In addition, the Oracle_IDM1 subdirectory represents the directory chosen for installing Oracle Identity Manager 11g, which may also need to be altered to match your installation environment.

Creating the Custom Tabs JAR File by Using JDeveloper

In this section, you use Oracle JDeveloper to generate the JAR file that contains the files needed to implement the custom tab added to the Self Service page. Your tasks include:

Note: Because the Custom Tabs (customizing_oim_ui_selfservice_tabs.zip) file contains the JDeveloper project (.jpr) file and the related sources, you first need to create a JDeveloper Application workspace into which the project can be opened. After the project (.jpr) file is opened in the application workspace you can modify the library path for the project before you compile the code to generate the required JAR file.

Extracting Source Files and Starting JDeveloper

.

In a Terminal window (or by using the File Browser application), navigate to the folder that contains the customizing_oim_ui_selfservice_tabs.zip file, and extract the contents of the file into a subdirectory, of your $HOME directory, where the subdirectory has the same name as the zip file. For example:

$ mkdir $HOME/customizing_oim_ui_selfservice_tabs
$ unzip customizing_oim_ui_selfservice_tabs.zip \
       -d $HOME/customizing_oim_ui_selfservice_tabs

Note: Alternatively, you can use the File Browser to create the new folder, open the JAR file in the Archive Manager from which you can extract the contents of the zip file into the new folder.

.

From your desktop or file system, if you have an desktop icon, double-click the desktop icon to launch Oracle JDeveloper. Alternatively, execute the following command line to start Oracle JDeveloper:

$ /opt/oracle/Middleware/jdeveloper/jdev/bin/jdev & 

Note: This command line example assumes you have installed Oracle JDeveloper in the /opt/oracle/Middleware/jdeveloper folder, where /opt/oracle/Middleware is your Middleware home (possibly defined in the MW_HOME environment variable).

Open and Configure the Custom Tab Project in JDeveloper

.

On the Oracle JDeveloper window, click New Application.

.

On the Create Generic Application - Step 1 of 2 page, accept default values in the "Name your application" section except for the Directory. Therefore, click Browse next to the Directory field:

.

In the Choose Directory dialog box, navigate to your $HOME/customizing_oim_selfservice_tabs directory (such as /home/oracle/customizing_oim_selfservice_tabs) or the directory in to which you extracted the files, and click Select.

.

On the Create Generic Application - Step 1 of 2 page, verify that the Application1 workspace Directory field contains your customizing_oim_ui_selfservice_tabs folder, and click Finish.

.

In the Oracle JDeveloper Application navigator panel, observe that the Application workspace (Application1) that you just created is displayed containing a newly created default project called Project1. Because you do not need this empty project you delete it by right-clicking the Project1 entry, and select Delete Project.

.

In the Confirm Delete Project dialog box, select the "Remove project and delete all of its contents (including source directories)" option, and click Yes.

.

In the Confirm Delete Project Contents Delete dialog box, click Yes.

.

To open the CustomTabs project file in the context of the Application1 workspace, click the Application Menu icon (on the right of the Application1 name drop-down box in the Application Navigator panel), and select Open Project.

.

In the Open Project dialog box, select the CustomTabs.jpr project file and click Open.

Note: If you are using a newer version of Oracle JDeveloper to the one used to create the CustomTabs.jpr project file and its sources, then when the Open Warning dialog box is displayed, to migrate the files into the new format compatible with the version of Oracle JDeveloper being used, click Yes.

Then when the Migration Status dialog box is displayed, click OK.

.

Finally, you should see the new CustomTabs project node appear under the Application1 workspace in the Application Navigator panel. To save the changes to the workspace, click the Save All icon in the Oracle JDeveloper toolbar.

Next you configure the library file paths needed to build (generate) the JAR file.

Modify the CustomTabs Project Library Paths

.

In the Oracle JDeveloper Application Navigator panel, double-click the CustomTabs project node to open its Project Properties window, or select the CustomTabs project node and click the Project Properties () icon.

.

In the Project Properties dialog box, select the Libraries and Classpath node in the left panel, select all the highlighted files listed below and click Remove.

Note: Oracle JDeveloper does not support modifying the path for these JAR and ZIP file entries, therefore we remove them all, and next add each of the JAR and ZIP files again with their correct directory paths that match your Oracle Identity Manager 11g installation environment.

.

In the Project Properties dialog box, in the Libraries and Classpath section click Add JAR/Directory:

In the Add Archive or Directory dialog box, navigate to the $MW_HOME/Oracle_IDM1/server/features folder (where $MW_HOME is the expanded path representing where your Oracle Middleware home directory is, and Oracle_IDM1 is the directory in which you installed Oracle Identity Manager), select the iam-features-identity.zip file, and click Select.


.

In the Project Properties dialog box in the Libraries and Classpath section, verify that the Classpath Entries list contains the iam-features-identity.zip file, and repeat the process of clicking "Add JAR/Directory" for each of the following files:

  • $MW_HOME/Oracle_IDM1/server/platform/iam-platform-entitymgr.jar
  • $MW_HOME/Oracle_IDM1/server/platform/iam-platform-utils.jar
  • $MW_HOME/Oracle_IDM1/server/platform/iam-platform-context.jar
  • $MW_HOME/Oracle_IDM1/server/features/iam-features-selfservice.zip
  • $MW_HOME/Oracle_IDM1/server/platform/iam-platform-authz-service.jar

.

In the Project Properties dialog box in the Libraries and Classpath section, verify that the Classpath Entries list contains all the files highlighted in the following image, and click OK to close the Project Properties dialog box:

.

To save the changes to the CustomTabs project , click the Save All icon in the Oracle JDeveloper toolbar.

 

Generate and Deploy the Custom Tabs JAR File

In this section, you use JDeveloper to create (generate) the adflibCustomTabs1.jar file, which contains the code that represents the panel and the Attribute and Password subtabs for the custom Authentication tab. You deploy the adflibCustomTabs1.jar file by copying the generated JAR file to the appropriate destination directory.

.

To create (generate)the adflibCustomTabs1.jar file, in Oracle JDeveloper, right-click the CustomTabs project and select Deploy > adflibCustomTabs1.

Note: While Oracle JDeveloper can deploy a JAR file directly to an application server runtime environment, in this case the deploy action selected has been pre configured through a JDeveloper deployment profile to create (write) the JAR file into the deploy subdirectory of the customize_oim_ui_selfservice_tabs directory (of the CustomTabs project).

The deployment profile has already been created in the Deployment section of the CustomTabs Project Properties. To view the deployment profile settings and the location where the JAR file is generated:

  • Select the CustomTabs project node, and click the Project Properties icon.
  • In the Project Properties dialog box, click Deployment.
  • On the Project Properties > Deployment page, select the adflibCustomTabs1 (ADF Library JAR File) entry and click Edit.
  • On the Edit ADF Library JAR Deployment Profile Properties dialog box, you can view the location of the generated JAR file, in this case the /oracle/home/customizing_oim_ui_selfservice_tabs/deploy directory.

Note: If you opened the Edit ADF Library JAR Deployment Profile Properties dialog box, click OK as many times as required until you close the Project Properties dialog box.

.

To deploy the JAR file into the correct Oracle Identity Manager 11g runtime context, in a Terminal window, copy the adflibCustomTabs1.jar file, from the $HOME/customize_oim_ui_selfservice_tabs/deploy directory to the $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF/lib directory, for example:

$ export MW_HOME=/opt/oracle/Middleware
$ cp $HOME/customize_oim_ui_selfservice_tabs/deploy/adflibCustomTabs1.jar \
 $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF/lib

Note: Alternatively, you can use the File Browser to copy the adflibCustomTabs1.jar file from the appropriate source to the specified destination directory. The command line syntax shown is Borne shell syntax, please use equivalent commands for your shell or command line environment.

Next you modify XML and property files for Oracle Identity Manager - Self Service console to be able to display the custom tab defined in the JAR file.

Configure Custom Tab and Self Service Console Property Files

In this section, for the Oracle Identity Manager 11g - Self Service console page to display the custom tabs (that is the Attribute and Password subtabs in the Authentication tab) correctly, you:

Note: You can edit the files by using Oracle JDeveloper as shown in this tutorial section, or using your preferred text editor.

.

Before you modify the faces-config-self.xml file contents, consider executing the following commands in a Terminal window to back up the original file:

$ cd $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF
$ cp faces-config-self.xml $HOME/backups 

Note: Instead of performing the next 7 steps in this section to modify the faces-config-self.xml file, you can right-click this faces-config-self.xml link to download and save the XML file on your system to replace the existing faces-config-self.xml file.

If you downloaded and replaced the faces-config.self.xml file then continue from step 9 in this section. Otherwise, continue from the next step to make the changes manually.

.

To open the faces-config-self.xml file for editing, in the Oracle JDeveloper window, select File > Open.

In the Open dialog box, browser to the /opt/oracle/Middleware/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF folder, select the faces-config-self.xml and click Open:

Note: Replace the /opt/oracle/Middleware and Oracle_IDM1 path elements to match your installation environment.

.

In the JDeveloper > faces-config-self.xml tabbed page, click the Source sub tab to view the XML and start editing the XML elements.

.

In the JDeveloper > faces-config-self.xml > Source tabbed page, add the following <managed-bean> XML element and its contents at the end of the XML document just before the last line containing the closing </faces-config> element:

    <!-- Custom Tab Page Info -->
    <managed-bean>
      <managed-bean-name>customPage</managed-bean-name>
      <managed-bean-class>oracle.iam.consoles.faces.backing.Self$OperationAction
</managed-bean-class>
<managed-bean-scope>application</managed-bean-scope> <managed-property> <property-name>id</property-name> <property-class>java.lang.String</property-class> <value>customization_page</value> </managed-property> <managed-property> <property-name>pageUrl</property-name> <property-class>java.lang.String</property-class> <value>/examples/MyProfile.jspx</value> </managed-property> </managed-bean>

Use the following image as a guide to the change made:

.

While editing the contents of the faces-config-self.xml > Source tabbed page, press Ctrl+Home to move to the top of the file, then press Ctrl+F and enter the search string primaryOperationsMap to locate the appropriate <managed-bean> entry.

.

In the faces-config-self.xml > Source tabbed page, insert the following XML elements just before the closing </map-entries> element inside the <managed-bean> element of the primaryOperationsMap managed bean:

    <!-- New custom fragments -->
    <map-entry>
      <key>#{customPage.id}</key>
      <value>#{customPage}</value>
    </map-entry>

For example:

.

To save the changes to the faces-config-self.xml file, click the Save icon or select File > Save.

.

To close the faces-config-self.xml file, select File > Close.

.

Next extract the Self.properties file from the iam-consoles-faces.jar file to add custom properties for the custom tab names. Consider creating environment variables as shown here for a Linux platform, and ensure the that JDK bin folder is in the execution path:

$ export MW_HOME=/opt/oracle/Middleware
$ export JAVA_HOME=/usr/java/jdk1.6.0_24
$ PATH=$JAVA_HOME/bin:$PATH

Execute the next commands to extract the /oracle/iam/consoles/faces/resources/Self.properties file from the iam-consoles-faces.jar file :

$ cd $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF/lib
$ cp iam-consoles-faces.jar $HOME/backups          # keep a backup of this file
$ jar xvf iam-consoles-faces.jar \
   oracle/iam/consoles/faces/resources/Self.properties           

Note: The Self.properties file is extracted into a directory tree that matches the JAR file path used to in the jar command.

.

Using gedit (your favorite editor or Oracle JDeveloper) open the file Self.properties file in the $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war/WEB-INF/lib/oracle/iam/consoles/faces/resources directory and add the following two property lines at the end of the file:

customization_page.text=Custom
customization_page.shortDesc=Custom Description.

Note: Instead of manually editing the Self.properties file, you can download this modified Self.properties file and replace the extracted version before you updated the Self.properties file in the JAR archive.

Note: If you manually edited the file, save the changes to Self.properties and close the file.

Additional Note: The first part of the resource name (property name) must match the id managed property value in the <managed-bean> element for the customPage bean added to the faces-config-self.xml.

.

In the Terminal window, to update (replace) the Self.properties file in the iam-consoles-faces.jar file, execute the following command:

$ jar uvf iam-consoles-faces.jar \
   oracle/iam/consoles/faces/resources/Self.properties

Note: The u option in the jar command line adds (updates) the file specified in the third argument into the JAR file named in the second argument.

Delete the modified Self.properties file and the directory tree into which it was extracted by executing the following command:

$ rm -rf oracle

.

In the JDeveloper window, select File > Exit to terminate Oracle JDeveloper. If you used a different editor to modify the Self.properties file, then close that editor application window.

Now all the customizations are complete, in the next section you restart Oracle Identity Manager and view the custom tab added to the Self Service console pages.

View the Custom Tabs in the Self Service Console

In this section, your tasks are to:

To complete these tasks, perform the following steps:

.

Restart the Oracle Identity Manager server by performing the following commands in a Terminal window:

$ export MW_HOME=/opt/oracle/Middleware
$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./stopManagedWebLogic.sh oim_server1

Wait for the Oracle Identity Manager WebLogic Managed Server instance to be shutdown, and then execute the following command to restart it.

$ cd $MW_HOME/user_projects/domains/base_domain/bin
$ ./startManagedWebLogic.sh oim_server1 &

Note: Wait until the Oracle Identity Manager 11g server instance is running. Remember to replace the usages of MW_HOME and base_domain with path names that match your installation.

.

In a web browser window or page, enter the URL http://localhost:14000/oim to access the Oracle Identity Manager Login page.

.

On the Oracle Identity Manager Login page, in the Sign In section enter the User Login xelsysadm and Password Welcome1, and click Sign In.

.

If the Oracle Identity Manager - Delegated Administration page is displayed first, then click the Self-Service icon or link.

.

On the Oracle Identity Manager - Self Service page, you can verify that the new Custom tab is appended to the original list of tabs (Welcome, Tasks, Requests, Profile) in the Self Service console page. If you move the mouse pointer over the Custom tab the text "Custom Description." as entered in the Self.properties file is displayed. Click the Custom tab.

Note: After accessing the Self Service console page, Oracle Identity Manager server creates a file called MyProfile.jspx file in the examples subdirectory of the $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war directory. The path /examples/MyProfile.jspx is defined in the pageURL managed bean property of the faces-config-self.xml file.

.

On the Oracle Identity Manager - Self Service > Custom tabbed page, you can view and explored the Attributes and Password sub tabbed pages implemented by the custom adflibCustomTabs1.jar file that you deployed into the Oracle Identity Manager runtime environment:

.

On the Oracle Identity Manager toolbar, click the Sign Out link.

 

Summary

About Making Changes to the Source and JAR File

When the user first accesses the Self Service console and a custom ADF tab, the MyProfile.jspx file is copied into iam-consoles-faces.war directory.

To view any changes made to the source resulting in a new JAR file being deployed, the existing MyProfile.jspx file needs to be deleted before the user accesses the Self Service console again. For example:

$ cd $MW_HOME/Oracle_IDM1/server/apps/oim.ear/iam-consoles-faces.war
$ rm /examples/MyProfile.jspx 

Note: The MyProfile.jspx file only exists after a user access the Self Service console.

In this tutorial, you have learned how to:

Resources

Credits (Optional)