Customizing Oracle Identity Manager User Interface Using Skins

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

Purpose

In this tutorial you learn how to customize Oracle Identity Manager(OIM) User Interface (UI) using custom ADF skins.

Overview

This tutorial demonstrates how you can use custom ADF skins for customization of the Advanced Administration console of Oracle Identity Manager 11g Release1 (11.1.1.3.0). It shows you how to make changes to the branding logo and the color scheme of the OIM UI.

Time to Complete

Approximately 30 minutes.

Software Requirements and Prerequisites

The following products must be installed before performing the customization task described in this tutorial:

Product Download Link / Install Guide
Oracle Database 11g, Release 1 http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html
Oracle WebLogic Server 11g, Release 1 http://www.oracle.com/technetwork/middleware/downloads/index-087510.html
Oracle Identity Manager 11g, Release 1 http://download.oracle.com/docs/cd/E14571_01/im.htm#oim

This tutorial assumes the Oracle Identity Manager installed on Windows OS and OIM home path to be set as D:\app\oracle\product\middleware\iam_home.

Customize the Advanced Administration Console

To use custom skins in OIM, perform the following steps:

  1. Download files provided for this tutorial
  2. Start WebLogic Server and Oracle Identtiy Manager
  3. Launch the OIM Advanced Administration console
  4. Customize the consoles by modifying appropriate files.
  5. Verify that the User Interface is customized according to your requirements

.

Download files provided for this tutorial

Click here to download files that are required for performing the customization described in this tutorial. Extract the files to a temporary folder on your local machine. The following screenshot shows the files that will be extracted.

 

.

Start WebLogic Server and Oracle Identtiy Manager

Make sure the WebLogic and OIM servers are up and running.

A. Click Start > Programs > Oracle WebLogic > User Projects > IdMDomain > Start Admin WebLogic Server Domain to start the WebLogic Admin server. This is the administrative server for the Identity Manager domain.

Verify that the server has started and is in running mode.

B. Start OIM server: Through command prompt navigate to the D:\app\oracle\product\middleware\user_projects\domains\IDMDomain\bin directory. Execute teh startManagedWebLogic.cmd command with oim_server1 as parameter. Provide the username and password relevant for the admin server, when prompted.

Note: oim_server1 is the name of the OIM server used in this tutorial. Replace the directory path and server name with values appropriate for your setup.

 

.

Launch the OIM Advanced Administration console

Launch the OIM Advanced Administration console to note the default user interface. You will customize this screen to change the logo, title, and the colors in the next section.

A.Open a browser window and use URL of the format http://hostname:7007/admin/faces/pages/Admin.jspx?.

Provide username and password for the OIM Server. This tutorial uses xelsysadm/welcome1 as username and password.

If you are challenged with Passowrd Management challenge questions, provide appropriate answers.

Verify that the console is launched.

 

 

.

Customize the Advanced Administration Console

In this section you customize appropriate files to modify the consolee look and feel. Specifically, you peform the following customizations:

  • Modifying the text that appears in the header banner of the console. This text is known as branding text.
  • Adding a logo to the console
  • Creating custom skins and style sheets to modify the appearance of the console, particularly the background color.

To customize the console, perform the following steps:

  1. Understand files that control the UI appearance
  2. Backup files before customization
  3. Copy the files provided to target folders to achieve customization

.

Understand files that control the UI appearance

This section describes the folders and files that control the appearance of the user interface for a deployed web application. This information helps you to identify which files need to be modified to achieve appropriate customization. The folders and files are referenced with respect to the location of a deployed web application under IAM_HOME. In this tutorial this is set to the path D:\app\oracle\product\middleware\iam_home\server\apps\oim.ear\iam-consoles-faces.war

Folder name: /templates: Templates are used to manage the layout of the pages. The ‘templates’ folder of the deployed web application has templates corresponding to each of the console and the login page. The following table explains the purpose of each of the templates available in the deployed web application iam_consoles-faces.war.

  • Template
    Purpose
    iam-consoles-faces.war/templates/IdmSignIn.jspx Login page.
    iam-consoles-faces.war/templates/self.jspx Authenticated self service console
    iam-consoles-faces.war/templates/uself.jspx Unauthenticated self service console
    IdmShell.jspx present in the deployed shared library for idm shell. See ‘Note 2’ on next page for details. Administration console
    iam-consoles-faces.war/templates/admin.jspx Advanced administration console

Folder name: /pages: Pages contain the actual content to be displayed on the UI. This folder of the deployed web application has pages for each of the console and the login page. The following table explains the purpose of each of the pages available in the deployed web application iam_consoles-faces.war.

  • Page
    Purpose
    iam-consoles-faces.war/pages/Login.jspx (Shown first time and when logging out of Advanced Administration console) admin.war/pages/Login.jspx (Shown after logging out of Administration console) Login page.
    self.jspx Authenticated self service console
    iam-consoles-faces.war/pages/uself.jspx Unauthenticated self service console
    IdmShell.jspx present in the deployed shared library for idm shell. See ‘Note 2’ on next page for details. Administration console
    iam-consoles-faces.war/pages/admin.jspx Advanced administration console

Apart from these generic pages for the consoles, there are others used for some specific pages like password management etc.

Folder name: /WEB-INF: Apart from other configuration files and descriptors, this folder contains the following two files useful for skin changes:

  • file
    Purpose
    trinidad-skins.xml This is used to introduce the definition of custom skin.
    trinidad-config.xml This is used to register the custom skin as the one to be used for the application.

To use the custom skin for Administration console, the trinidad-skins.xml has to be copied to the admin.war/WEB-INF location.
/skins: This folder contains some ootb skins. The custom skin can be created here and its location should be used in the definition of the skin in trinidad-skins.xml (through the “style-sheet-name” tag).

NOTE 1: Although the example is to show application of custom skins, some changes are required in the pages and templates to get expected results. For example, templates or pages can apply some hardcoded background colors that might need to be removed or changed.

NOTE 2: The templates used by admin.war for Administration console and login page are in the deployed shared library oracle.idm.uishell. To make any changes to these templates, use the Weblogic console to get the path of oracle.idm.uishell.war. Unpackage this war file and the oracle-idm-uishell.jar in WEB-INF/lib, make the changes, repackage and redeploy. Before redeploying the shared library the OIM application needs to be stopped since that refers to this library. Start the application after the redeploying of the library.

Backup files before customization

Before updating various files to achieve customization, it is a best practice to backup the default OOTB. Create a file under.D:\app\oracle\product\middleware\iam_home\server\apps\oim.ear\admin.war\WEB-INF\lib directory. Take a backup of the files under ias-console-files.war folder.

Shutdown the servers before customizing the files

Run command stopManagedWeblogic.cmd from the director d:\app\oracle\product\middleware\iam_home\server\apps\oim.ear\iam-consoles-faces.war to stop the WL server and the OIM server. Close the browsers where the consoles are open.

Copy the files for customization

Now to perform customization at various levels, copy the files you downloaded into the target places as described in the following table:

Source Folder
Source files
Purpose of the files
Steps for Customization
  iam-consoles-faces.war and admin.war Deployed web applications  
/images acme_03_02.bmp
button_bg.gif
Logo change and background for the command buttons Copy the images to iam-consoles-faces.war/images folder.
/pages admin.jspx The changes in Admin.jspx reflect the following change on UI:
The navigation links to other consoles (Self Service and Administration) have a light color based on the theme="dark" property. By removing this theme, these links take the color from the stylesheet.
Replace the existing Admin.jspx with the new one at iam-consoles-faces.war/pages.
/properties Admin_en.properties The Admin_en.properties changes will include changing the title and branding text. Replace Admin_en.properties file at the following location:
iam-consoles-faces.war/WEB-INF/lib/iam-consoles-faces.jar/oracle/iam/consoles/faces/resources.
To modify the file inside the iam-consoles-faces.jar, the jar files needs to be unpackaged and repackaged with the changes.
1. Unpack the iam-consoles-faces.war/WEB-INF/lib/iam-consoles-faces.jar (using winzip or "jar -xvf" command).
2. Replace the properties file at the above location (oracle/iam/consoles/faces/resources).
3. Repack the jar (using winzip or "jar -cvf" command) and replace the equivalent file in the folder iam-consoles-faces.war/WEB-INF/lib.
/skins/myskin myskin.css The new skin uses a number of ADF styleclasses and overrides the properties. This result in customizing the UI with different background, foreground colors etc. Create the folder structure iam-consoles-faces.war/skins/myskin and place the myskin.css in that folder. For a comprehensive list of ADF styleclasses, please refer to the Oracle Identtiy Manager 11g documentation on customization.
/templates admin.jspx The changes in the admin.jsp template reflect in the following changes on UI:
1. To remove inline white background on the top branding header. This will allow the stylesheet value to take effect.
2. To remove the spacer image on the top branding header so that the background color shows up evenly instead of an image with gradient colors.
Replace the admin.jspx with the existing one at iam-consoles-faces.war/templates. The admin_original.jspx is provided only for comparison purpose.
/WEB-INF trinidad-config.xml
trinidad-skins.xml
The trinidad xml file changes are as follows:
1. trinidad-skins.xml: Define a new skin and specify the corresponding css file.
2. trinidad-config.xml: Refer to the new custom skin for OIM application.
Replace the existing trinidad-skins.xml and trinidad-config.xml with the new ones at iam-consoles-faces.war/WEB-INF.

Clean up temporary files

The server creates temporary files which include compiled versions of the jspx files. Clean up the tmp folder to remove all existing temporary files so that they are recreated with the newly modified files. Remove all the files inside the following location:

../middleware/user_projects/domains/base_domain/servers/oim_server1/tmp

Restart the servers and the consoles

Using the procedure described previously. start the servers and open browser windows with the OIM Advanced Administration Console open. Now you should be able to view the cusotmized UI interface where the logo and the branding are changed. View the following screenshot for a sample of how the UI appears after the customization.

 

Resources

Credits (Optional)