30 Customizing the Interface

This chapter explains how to customize various aspects of the user interfaces available in Oracle Identity Manager.

Note:

Oracle Identity Manager 11g Release 2 (11.1.2) includes a number of UI pages based on earlier UI technologies known as transitional UIs. Due to technical differences, the transitional UIs are displayed in popup windows and have a different look and feel. These UIs are discussed in the relevant sections in this chapter.

The Identity Self Service user interface (UI) in Oracle Identity Manager is based on Application Development Framework (ADF), which ensures consistent customization. ADF allows UI customization that is safe from patches and upgrades. This means that after you apply patches to Oracle Identity Manager or upgrade Oracle Identity Manager, the UI customizations are preserved.

This chapter describes customizing various aspects of the UI in the following sections:

30.1 Customization Concepts

This section describes the concepts related to UI customization in the following sections:

30.1.1 Deployment of UI Libraries and Applications

ADF supports inbuilt customization and MDS customization. The customization is achieved by developing new UI artifacts or skins, and packaging them in custom library WAR files. Skins and stylesheets are mechanisms to allow customization of the look and feel of the UI. The advantage of using stylesheet changes and custom skins is that they are centralized changes and easier to manage.

Figure 30-1 shows the various Oracle Identity Manager UI libraries and their dependency structure.

Figure 30-1 Oracle Identity Manager UI Libraries

Description of Figure 30-1 follows
Description of "Figure 30-1 Oracle Identity Manager UI Libraries"

The custom library is a placeholder library that you can use to add new taskflows built by using the default libraries. The Self Service EAR declares weblogic.xml dependency on the library-ref name oracle.iam.ui.custom. This library is provided by oracle.iam.ui.custom-dev-starter-pack.war. You can change the WAR file name for the custom library per naming conventions in your organization. However, the deployment name (library extension name in MANIFEST.MF) must be retained as oracle.iam.ui.custom. Otherwise, Self Service ear will not be deployed.

The deployment name is oracle.iam.ui.oia-view.

30.1.2 Overview of MDS Customization

Using the customization features provided by MDS, you can create applications that fall into the following customization patterns:

  • Seeded customization: Seeded customization of an application is the process of taking a generalized application and making modifications to suit the requirements of a particular group, such as a specific industry or site. Seeded customizations exist as part of the deployed application, and endure for the life of a given deployment.

  • User customization: User customization allows an end user to change the content of the application at runtime to suit individual preferences (for example, which columns are visible in a table), and have those changes retained the next time the user opens the application.

  • Runtime customization: Using the features of Oracle WebCenter, you can create applications that are customizable at runtime. This allows business analysts or administrators to customize the application for their end users by using a Web browser interface.

For detailed information about customizing applications with MDS, see "Customizing Applications with MDS" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

30.1.3 Overview of the Web Composer

Oracle Web Composer is an innovative component that enables any application or portal to be customized or personalized after it has been deployed and is in use. Oracle Web Composer runs in all modern Web browsers and enables editing JSF applications and portal pages by selecting information and components from the Business Dictionary or Resource Catalog.

The customization capabilities of the Web Composer include inserting a logo or altering the colors to match those of your company, and complex customizations, adding items to a page, changing the layout of a page, altering a supplied process, and specifically tailoring the delivered application or portal to meet any business requirement. These customizations can be stored in the Oracle Identity Manager database by using Oracle Metadata Services (MDS). For example, to store customizations in the database, the Web Composer creates a copy or sandbox for the pages as they are being edited. The sandbox is a temporary storage area to save a group of runtime page customizations before they are either saved and pushed to other users, or discarded. In this way, customizations can be previewed by others and approved for use before they are visible to all users. See "Managing Sandboxes" for more information about sandboxes.

Personalization changes your view of the interface or application page. Other users are not affected by the changes you make to a page. The pages can be personalized by individual users to add any combination of components to their page whenever they want them without affecting the view of the page for other users.

Oracle Web Composer is integrated with Oracle WebCenter Framework and WebCenter Services. You can add Oracle Web Composer components to your JSF application pages to enable users to edit those pages at runtime. You can add the components at any time during the development lifecycle, when the requirements of the application demand it. In addition, you can use the page service to enable users to create pages at runtime. Oracle Web Composer has been leveraged inside Oracle WebCenter Spaces to allow users to customize and personalize personal and group spaces. The Oracle WebCenter Spaces application provides a working example of how users can take an active role in managing and altering their work environment to match their specific requirements. Figure 30-2 shows the Oracle Web Composer architecture.

Figure 30-2 Oracle Web Composer Architecture

Description of Figure 30-2 follows
Description of "Figure 30-2 Oracle Web Composer Architecture"

30.2 Managing Sandboxes

All customizations and form management are performed in a sandbox. A sandbox allows you to isolate and experiment with customizations without affecting the environment of other users. Any changes made to a sandbox are visible only in the sandbox. You must create and activate a sandbox to begin using the customization and form management features. After customizations and extending forms are complete, you can publish the sandbox to make the customizations available to other users.

Some of the sandbox operations are:

  • Activate: You must activate a sandbox to use it. After you activate the sandbox, any changes to metadata objects are stored in the sandbox only. There can be only one active sandbox at a time. The information about the active sandbox is stored in the session. Therefore, a sandbox must be activated to continue with customization after every login to Oracle Identity Manager.

    Caution:

    After creating a sandbox, you must activate it. If you do not activate a sandbox, then you will not be allowed to perform operations on the sandbox later, or might not get the desired result. For example, if you create a sandbox but do not activate it, create a disconnected application instance, run catalog synchronization scheduled job, login to Identity System Administration, and try to checkout the disconnected application instance on the Catalog page, an error will be generated. You can perform this operation without any error, if you activate the sandbox after creating it and after every login to Identity Self Service or Identity System Administration.

  • Deactivate: Reverse operation to activating a sandbox. If no sandbox is active, then changes to metadata objects are not allowed, and therefore, no UI customization is allowed.

  • Publish: You must publish a sandbox to merge the changes stored in the sandbox to the mainline and make it available to other users. After you publish the sandbox, the changes are merged to the mainline and cannot be reverted. The sandbox can no longer be activated, deactivated, exported, or deleted.

    Note:

    Before publishing a sandbox, close all tabs and pages of the Identity Self Service or Identity System Administration, and export the sandbox to a ZIP file to have a backup of UI customizations done.

    Oracle recommends creating a backup of the MDS before publishing any sandbox. MDS backup can be created by using tools, such as Oracle Enterprise Manager. See "Creating MDS Backup" for information about creating a backup of the MDS by using Oracle Enterprise Manager.

  • Export: You can export all changes stored in the sandbox including sandbox metadata to a ZIP file. Then, you can import these changes to the same or another environment.

  • Import: You can import the sandbox archive (ZIP file) to an environment. Imported sandbox can be used normally as it would have been created in the environment. Beware when importing sandboxes that any available sandbox with the same name will be overwritten by the imported sandbox.

    Caution:

    Any available sandbox with the same name is overwritten by the imported sandbox.

Sandbox management and sandbox operations resemble operations with concurrent versioning system. You can think of a sandbox as a branch in CVS. Creating a sandbox is similar to creating a branch. Activating a sandbox is similar to performing changes on top of the branch, and publishing a sandbox is similar to merging the content of the branch to the main branch, sometimes referred to as trunk.

Note:

When you create a sandbox, a new branch is created. You can modify MDS content within that branch. Note that you will not be able to view the changes made in other sandboxes that are created later and published to the main branch. Similarly, when you try to merge this sandbox, a concurrent modification exception is generated. It is recommended that you edit the contents of the sandbox manually to remove the conflicting files. However, if manual editing is not possible, then create a new sandbox again and redo the change.

This section describes how to manage sandboxes in the following sections:

30.2.1 Handling Concurrency Conflicts

Multiple users can customize an application by using sandboxes. While doing so, the following types of concurrency conflicts might take place:

  • Conflicts within a sandbox: Users overwriting changes created by other users, either directly by changing the same artifact, or indirectly by affecting files that are shared between the artifacts.

    Conflicts within a sandbox can arise when multiple users are customizing an application by using the same sandboxes at the same time, because more than one user may be attempting to customize the same artifact, or performing a customization task that indirectly affects other shared files. An example of a direct conflict is when different users attempt to customize the same page, the same fragment, or the same metadata file in the same layer. An example of an indirect conflict is when two users, each creating their own object, cause a conflict in the metadata file that tracks which new objects have been created by both saving their changes around the same time. Conflicts may also arise when users are editing a shared artifact, such as when a user performs an operation that adds or edits a translatable string. For example, a user edits a field's display label or help text, or a validation rule's error message, while another user performs an operation around the same time that similarly affects translatable strings. Another example of a shared artifact conflict is when two or more users are working in navigator menus which are shared across applications.

  • Conflicts between sandboxes intended for publishing: Multiple sandboxes with the same customized artifact publishing to the mainline.

    Conflicts between sandboxes can arise when there is more than one sandbox intended for publishing in use. If two sandboxes contain conflicting customization changes to the same artifact and both are being published, then the sandbox that is being published last will not be allowed to be published, and an error describing the conflict will be displayed. To avoid such conflicts, it is recommended to create and use only one sandbox at a time. These types of conflicts can also occur with shared metadata files such as resource bundles that store translatable strings.

When multiple users are working in a single sandbox, these guidelines must be followed:

  • Multiple concurrent users in the same sandbox must operate only on different and unrelated objects. For example, if user1 updates object1, then user2 can update object2 but should not update object1. Be aware that if both modifications involve changes to translatable strings, then saving changes to separate objects around the same time may still cause a conflict in the resource bundle that stores the translatable strings.

  • Users in the same sandbox can see the changes created by one another. The latest version of each object gets loaded on-demand the first time it is viewed. If there are ADF Business Components customizations, then users must log out and log in again to see those changes reflected in the UI.

When multiple users are working in multiple sandboxes, in addition to all guidelines applicable to multiple users working in a single sandbox, these guidelines must be followed:

  • There can be any number of test-only sandboxes operating concurrently. Multiple users can use multiple sandboxes concurrently for testing even if these sandboxes are never published. Sandboxes that are used for testing only, and that are not published, cause no conflicts with each other, but all guidelines for multiple users working in a single sandbox must be followed. However, all modifications are lost when the sandboxes are deleted.

  • For sandboxes that will be published, you can have multiple concurrent sandboxes only if they operate on mutually exclusive artifacts. For example, you can have one sandbox that contains a page that is being customized to add a task flow, and another sandbox that contains a different page from a different application.

  • If an artifact is updated in both the mainline and in the sandbox (or two different sandboxes), when the sandbox is published, such conflicts are detected and an error is generated.

30.2.2 Creating a Sandbox

To create a sandbox:

  1. Log in to Oracle Identity Self Service or Oracle Identity System Administration.

  2. On the upper navigation bar, click Sandboxes. The Manage Sandboxes page is displayed. This page has the following sections:

    • Available Sandboxes: Displays all the sandboxes that are available for testing the UI customizations, which are not yet published.

    • Published Sandboxes: Displays all the published sandboxes.

  3. On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.

  4. In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.

  5. In the Sandbox Description field, enter a description of the sandbox. This is an optional field.

  6. Click Save and Close. A message is displayed with the sandbox name and creation label.

    Caution:

    Selecting the Activate Sandbox option closes all the open tabs except the Manage Sandboxes tab and activates the created sandbox.

  7. Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.

30.2.3 Activating and Deactivating a Sandbox

To activate a sandbox:

Note:

You must close all tabs in the Self Service or System Administration interfaces before activating or deactivating a sandbox.

  1. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to activate.

  2. On the toolbar, click Activate Sandbox.

    The table refreshes and a marker in the Active column is displayed. In addition, the Sandboxes link on the upper navigation bar also displays the active sandbox name in parentheses.

    Caution:

    If any other tabs are open except the Manage Sandboxes tab before activating the sandbox, then Oracle Identity Manager prompts that all the tabs will be closed before the sandbox can be activated.

To deactivate a sandbox:

  1. From the table showing the available sandboxes in the Manage Sandboxes page, select the active sandbox that you want to deactivate.

  2. On the toolbar, click Deactivate Sandbox. The page refreshes and the marker in the Active table disappears.

    Caution:

    If any other tabs are open except the Manage Sandboxes tab before activating the sandbox, then Oracle Identity Manager prompts that all the tabs will be closed before the sandbox can be activated.

30.2.4 Viewing and Modifying Sandbox Details

To view the details of a sandbox and modify the details:

  1. In the table showing the available sandboxes in the Manage Sandboxes page, click the sandbox name link. A dialog box with the sandbox details is displayed.

  2. Make the following changes:

    • In the Description field, you can enter a description for the sandbox.

    • View all the changes to the sandbox in the Change Details table.

    • Filter sandbox changes by using the Layer Names, Layer Values, and Change Types lists, and the Filter toolbar icon.

    • Delete any changes made in the sandbox by selecting the change in the table, and clicking Delete Customization.

    • Export the sandbox, if it contains any changes, by clicking Export Sandbox.

30.2.5 Exporting and Importing a Sandbox

To export a sandbox from an Oracle Identity Manager deployment to another:

  1. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to export.

  2. On the toolbar, click Export Sandbox.

    If the sandbox contains any changes, then the sandbox content ZIP file starts downloading. You can now take the ZIP file and import it to the same or another environment.

    Note:

    The name of the sandbox ZIP file is not the sandbox name. The sandbox name usually starts with IdM_ and it is specified in the XML file located inside the ZIP in the /mdssys/sandbox/ directory.

    Caution:

    If the deployment on which the sandbox content ZIP file is being imported already contains a sandbox with the same name, then that sandbox will get overwritten.

To import a sandbox from an Oracle Identity Manager deployment to another:

  1. On the toolbar, click Import Sandbox. The Import Sandbox dialog box is displayed.

  2. In the Sandbox Archive field, enter a path to the sandbox archive that you exported.

  3. Click Import.

    The sandbox is imported to the target deployment and is displayed in the Available Sandboxes tab.

30.2.6 Publishing a Sandbox

To publish a sandbox:

Note:

Oracle recommends creating a backup of MDS before publishing the sandbox. A backup of MDS can be created by using Oracle Enterprise Manager. See "Creating MDS Backup" for information about creating a backup of the MDS by using Oracle Enterprise Manager.

  1. Before publishing the sandbox, close all the open tabs and pages.

  2. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to publish.

  3. On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.

  4. Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.

  5. You can click the Published Sandboxes tab to view a list of the published sandboxes.

30.2.7 Checking Out an Item from Cart

To check out an item from cart:

  1. Log in to Oracle Identity Self Service.

  2. Create a sandbox. See "Creating a Sandbox" for information about creating a sandbox.

  3. Activate the Sandbox that you created. See "Activating and Deactivating a Sandbox" for information about activating sandbox.

    Note:

    If you don't activate the sandbox and try to add the application instance to catalog, you will encounter an error.

  4. Create a disconnected application instance "disc1". By default it will be published to top. See "Creating a Disconnected Application Instance" section in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for information about creating a disconnected application instance.

  5. Publish the Sandbox. See "Publishing a Sandbox" for information about publishing a sandbox.

  6. Run Catalog Synchronization Job.

  7. Log in to Oracle Identity System Administration.

  8. Click on Catalog and search for "disc1".

  9. Click Add to add the item to the cart.

  10. Click Checkout from Cart.

30.2.8 Deleting a Sandbox

To delete a sandbox:

  1. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to delete.

  2. On the toolbar, click Delete Sandbox. A message is displayed asking for confirmation.

  3. Click Yes to confirm. The sandbox is deleted and is no longer displayed in the Manage Sandboxes page.

Note:

Deleting a sandbox does not delete the forms created while the sandbox is active. Deleting forms is not supported in this release of Oracle Identity Manager.

30.2.9 Reverting Changes to Default Settings

You must perform all customizations within a sandbox. Until the sandbox is published, the changes are visible to you only and can be easily reverted by deactivating or deleting the sandbox. After the sandbox is published, the changes done cannot be reverted.

You can remove specific changes from the sandbox in any one of the following ways:

  • Export the sandbox and modify it manually.

  • Navigate to the Manage Sandboxes page, open the details of your sandbox, select a change, and delete it by clicking Delete Customization.

When an MDS sandbox is published, the documents are commited to the MAIN line. Your application starts using these documents immediately, and the application user views the effect of publishing the sandbox. Sometimes, you might inadvertently publish an incomplete or a wrong sandbox. In such instances, it is possible to recover your MAIN line to the state just before you created the wrong sandbox.

For example, if you create a sandbox called ShowAdminFeature at time T1, and in that you customized a JSFF fragment published at time T2. You realize later that the sandbox you published is wrong, and you want to recover your state to time T1. To do so:

  1. Login to Oracle Enterprise Manager.

  2. On the left pane, expand Application Deployments, Resource Adapters, and select the oracle.iam.ui.console.self-service application.

  3. On the top of the right pane, click Application Deployment, and select MDS Configuration.

  4. At the lower part of the right pane, click the Runtime MBean Browser link. The screen refreshes.

  5. Click the Operations tab.

  6. Scroll down and select the listMetadataLabels MBean operation, and then click Invoke. All the sandboxes precreation labels and postpublish labels are displayed. Select the sandbox precreate to which you want to restore and copy it to clipboard.

  7. Click Return to go back to the operations.

  8. Select the promoteMetadataLabel MBean operation and invoke it by provising the value that you copied in step 6.

  9. Restart oim_server1.

    Your MDS main line is reverted to the state that was at the time of creation of the sandbox.

Note:

You can also restore to the last successful sandbox that was published by restoring to the post label of that sandbox.

30.3 Skin Customization in Oracle Identity Manager

Oracle ADF uses skins along with styles to customize the appearance of an application. These concepts apply to all the Oracle Identity Manager interfaces, with the exception of the Transitional UI popups.

See Also:

Before customizing style sheets, see Customizing the Appearance Using Styles and Skins in the Fusion Middleware Web User Interface Developer's Guide in the following URL:

https://download.oracle.com/docs/cd/E15523_01/web.1111/b31973/toc.htm

Following URL gives a list of all the CSS style selectors that can be used to customize the style sheets:

https://download.oracle.com/docs/cd/E15523_01/apirefs.1111/e15862/toc.htm

You configure new skins in trinidad-config.xml. The default skin for Oracle Identity Manager is "fusion":

<?xml version="1.0" encoding='utf-8'?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <skin-family>fusion</skin-family>
</trinidad-config>

There are two console-specific trinidad-config.xml files. The files are in the following directory paths:

  • oracle.iam.console.identity.self-service.ear/oracle.iam.console.identity.self-service.war/WEB-INF/

  • oracle.iam.console.identity.sysadmin.ear/oracle.iam.console.identity.sysadmin.war/WEB-INF/

30.3.1 Configuring Skins

To keep the defaults coming from the "fusion" skin and override certain style sheet elements:

  1. Create the skin in the trinidad-skins.xml file. Make a copy of the trinidad-skins.xml from the /iam-consoles-faces.war/WEB-INF/ directory to the admin.war/WEB-INF/ directory. For both the /admin.war/WEB-INF/trinidad-skins.xml file and the /iam-consoles-faces.war/WEB-INF/trinidad-skins.xml file, make following changes:

    <?xml version="1.0" encoding='utf-8'?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
    <skin>
        <id>myskin.desktop</id>
        <family>myskin</family>
        <extends>fusion.desktop</extends>
        <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
        <style-sheet-name>skins/myskin/myskin.css</style-sheet-name>
        <bundle-name>oracle.iam.consoles.faces.resources.AdfComponentsMessageBundle</bundle-name>
    </skin>
</skins>

  2. Register the new "myskin" in both the admin.war/WEB-INF/trinidad-config.xml file and the iam-consoles-faces.war/WEB-INF/trinidad-config.xml file, as shown:

    <?xml version="1.0" encoding='utf-8'?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <skin-family>myskin</skin-family>
</trinidad-config>

  3. Create myskin.css at both the admin.war/skins/myskin/myskin.css and iam-consoles-faces.war/skins/myskin/myskin.css files.

  4. Put stylesheet elements that are required to be overridden from the defaults. For example, to change the branding text color, add the following:

    .AFBrandingBarTitle, .xdj
{
        color:#800080;
}

  5. Redeploy (or update) the Oracle Identity Manager deployment through the Oracle WebLogic Server Administration Console.

Note:

To change the branding information as an alternative to the method in "Changing Branding and Logo", create a custom skin and use the appropriate style classes given in the URL in this section.

30.3.2 Creating a New Skin

To create a new skin:

  1. In the WEB-INF directory, create the trinidad-skins.xml file, as shown:

    <?xml version="1.0" encoding='utf-8'?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
    <skin>
        <id>wells.desktop</id>
        <family>wells</family>
        <extends>fusionFx-v1.desktop</extends>
        <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
        <style-sheet-name>skins/wells/wells.css</style-sheet-name>
    </skin>
</skins>

  2. Create the trinidad-config.xml file, as shown:

    <?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <skin-family>fusion</skin-family>
</trinidad-config>

  3. Configure the following system properties:

    • Skin Family for OIM UI: The ADF skin family for Oracle Identity Manager UI that the application uses at runtime.

    • Skin Version for OIM UI: The skin version, if any, for the skin family being used for Oracle Identity Manager UI.

      See Also:

      "System Properties in Oracle Identity Manager" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about the Skin Family for OIM UI and Skin Version for OIM UI system properties

    Change the values of these properties to your custom skin. Before setting the values of these properties, the custom ADF skin must be developed and then deployed into Oracle Identity manager.

    Oracle ADF faces provide simplified default skins, such as fusionFx-simple-v2.desktop, which are designed to be extended by custom skins. The ADF skin that you create must extend either one of the ADF skins that Oracle ADF provides or from an existing ADF skin that you created. Skins are reusable components and must be created in their own JDeveloper project or workspace. You can create an ADF skin file in the ADF Skin Editor that defines how ADF faces components render at runtime.

    See Also:

  4. If required, adjust the height of the top branding bar to fit the new logo image in the following:

    oracle.iam.console.identity.self-service.ear/oracle.iam.console.identity.self-service.war/oracle/iam/ui/main

    For the login page (signin.jspx):

    <f:attribute name="globalBrandingSize" value="64"/>

    For the page displaying challenge questions (firstlogin.jspx):

    <f:attribute name="globalHeaderSize" value="64"/>

    For the pages in Identity Self Service (identity.jspx):

    <f:attribute name="globalHeaderSize" value="64"/>

  5. In the oracle.iam.console.identity.self-service.ear/oracle.iam.console.identity.self-service.war/WEB-INF/web.xml file, include the following settings:

    <context-param>
  <description>No obfuscation of CSS.</description>
 <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name>
  <param-value>true</param-value>
</context-param>
<context-param>
  <description>If this parameter is true, there will be an automatic check of the modification date of your JSPs, and saved state will be discarded when JSP's change. It will also automatically check if your skinning css files have changed without you having to restart the server. This makes development easier, but adds overhead. For this reason this parameter should be set to false when your application is deployed.</description>
  <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
  <param-value>true</param-value>
</context-param>

30.4 Customizing Pages at Runtime

Customizing Oracle Identity Manager can be broadly categorized into customizing the UI and extending the object definitions of the user, role, catalog, and provisioning target resource entities.

Table 30-1 lists the artifacts that can be customized for each entity.

Table 30-1 Entity Artifacts for Customization

Enity Artifacts

User

Create Page

Modify Page

User Attribute Details

Advanced Search Interface

My Information

Self Registration

Role

Create Page

Modify Page

Advanced Search Interface, which includes:

- Query Criteria

- Results Table columns

Catalog

Catalog Search Page that includes:

- Results Table columns

- Catalog Item Details

Provisioning target resource

Provisioning Target Resource Create Form

Provisioning Target Resource Modify Form

Provisioning Target Resource Bulk Form

See Also:

"Managing Forms" and "Configuring Custom Attributes" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about creating and managing forms by using the Form Designer

This section contains the following topics:

The Web Composer enables you to customize the UI at runtime. This section describes the following UI customizations:

30.4.1 Using Expression Language in UI Customization

Expression Language (EL) allows you to access application data stored in JavaBeans components. For an introduction to EL and EL expression syntax, refer to the following URL:

http://developers.sun.com/docs/jscreator/help/2update1/jsp-jsfel/jsf_expression_language_intro.html

30.4.1.1 Avaliable EL Expressions in the User Context

The OIMContext bean is defined as an ADF session scope bean in adfc-config.xml in your project. Table 30-2 lists the available EL expressions in the Oracle Identity Manager user context.

Table 30-2 EL Expressions in User Context

EL Description 
#{oimcontext.currentUser['ATTRIBUTE_NAME']}

Access value of the ATTRIBUTE_NAME attribute of the logged-in user.For the list of default attributes defined for the user entity, see "Attribute Definitions" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

 
#{oimcontext.currentUser['UDF_NAME']}

Access value of the UDF_NAME attribute of the logged-in user. UDF attributes can be defined by using the Form Designer.

 
#{oimcontext.currentUser.roles}

Access the ROLE_NAME and RoleEntity mapping that contains the roles assigned to the logged-in user. RoleEntity is Java Bean having name, description, key, and displayName properties.

 
#{oimcontext.currentUser.roles['SYSTEM ADMINISTRATORS'] != null}

Boolean EL that evaluates to true if the logged-in user has the System Administrator admin role. Similarly, you can modify the EL to check for any other role.

 
#{oimcontext.currentUser.adminRoles['OrclOIMSystemAdministrator'] != null}

Boolean EL that evaluates to true if the logged-in user has the OrclOIMSystemAdministrator admin role. Similarly, you can modify the EL to check for any other admin role.

You can use EL expression to retrieve all available user attribute values from the oimcontext bean, as shown in the following examples:

  • To get the user key of the currently logged-in user:

    #{oimcontext.currentUser.usr_key}

    OR:

    #{oimcontext.currentUser['usr_key']}

  • To get the list of role names of the currently logged-in user:

    #{oimcontext.currentUser.roles}

  • To get the list of admin role names of the currently logged-in user:

    #{oimcontext.currentUser.adminRoles}

As an example, if you want to display a message with the user login name when a user logs in to Oracle Identity Self Service, then you can use EL expression to retrieve the login name of the currently logged-in user, and display it on the page. The expression to retrieve the user login name is the following:

#{oimcontext.currentUser['User Login']}

30.4.1.2 Available EL Expressions in the RequestFormContext

RequestFormContext is a bean available in the pageFlowScope of entity form details task flow. The entity forms include user form, application instance form, role form, and entitlement form. RequestFormContext provides various context information. Using this context information, you can customize the forms based on specific business requirements.

Table 30-3 lists the EL expressions involving RequestFormContext.

Table 30-3 EL Expressions in RequestFormContext

EL Description 
#{pageFlowScope.requestFormContext}

Access current instance of RequestFormContext.

 
#{pageFlowScope.requestFormContext.operation}

Access operation type that is being performed on the entity. The possible values are CREATE and MODIFY.

 
#{pageFlowScope.requestFormContext.operation == 'MODIFY'}

Boolean EL that evaluates to true if current operation being performed on the entity is MODIFY.

 
#{pageFlowScope.requestFormContext.actionType}

Access action that is being performed by the user when the entity form is displayed. The possible values are APPROVAL, FULFILL, REQUEST, VIEW, and SUMMARY.

 
#{pageFlowScope.requestFormContext.actionType == 'REQUEST'}

Boolean EL that evaluates to true if the action that is being performed by the user when the entity form is displayed is REQUEST, for example, requesting role or application instance.

 
#{pageFlowScope.requestFormContext.bulk}

Boolean EL that evaluates to true if the operation being performed is a bulk operation, for example, requesting multiple application instances at a time.

 
#{pageFlowScope.requestFormContext.beneficiaryIds}

Access the list of beneficiary or target user IDs. For example, if you are requesting an application instance for user John Doe, then the list contains the user ID of John Doe.

Note: Oracle recommends accessing the list and performing operations on it by using Java code. For more information please refer to

 
#{pageFlowScope.requestFormContext.cartItemIds}

Access the list of cart item IDs. For example, if you are requesting an application instance for a user, then the list contains the application instance ID that is being requested.

Note: Oracle recommended accessing the list and performing operations on it by using Java code. For more information please refer to

 
#{pageFlowScope.requestFormContext.requestEntityType}

Get entity type being requested. The possible values are ROLE, ENTITLEMENT, APP_INSTANCE, and USER.

 
#{pageFlowScope.requestFormContext.requestEntityType == 'APP_INSTANCE'}

Boolean EL that evaluates to true if the entity type being requested is APP_INSTANCE.

 
#{pageFlowScope.requestFormContext.requestEntitySubType}

Access subtype of entity being requested. For example, when requesting APP_INSTANCE, requestEntitySubType is the application instance key.

 
#{pageFlowScope.requestFormContext.instanceKey}

Access the key of the instance being modified.

30.4.1.3 Internationalization for Resource Strings

In Oracle Identity Manager, you can create custom resource bundles and reference them in the UI. If you want to modify some of the predefined UI elements such as labels, headers, and so on, or the values displayed on a certain page (for example, values displayed in the Status field of the Request Summary page), then perform the procedure described in this section.

To create custom resource bundles:

  1. Open the custom project WAR file, which is oracle.iam.ui.custom-dev-starter-pack.war.

  2. Create a new CustomResourceBundle.properties file in the WEB-INF/classes/oracle/iam/ui/custom/ directory.

  3. In the new file, enter the key value pairs, for example:

    CUSTOMRB_BANNER_TEXT=My Identity and Access

  4. Create all localized files, for example CustomResourceBundle_it.properties and CustomResourceBundle_es.properties, in the same directory.

  5. Repackage the custom WAR, and update the custom WAR deployment in the server.

To use the resource bundles:

  1. In Oracle Identity Self Service, create a sandbox, and click Customize.

  2. On the Component Properties dialog box, open the Expression Editor for the specific property, and specify the expression, for example:

    #{adfBundle['oracle.iam.ui.custom.CustomResourceBundle'].CUSTOMRB_BANNER_TEXT}

  3. Click Test to test the expression. Click OK, then click Apply.

  4. Click OK to close the Component Properties dialog box.

  5. Export the sandbox, and then publish the sandbox.

    Note:

    Exporting the sandbox is optional, but it is a recommended step.

30.4.2 Showing or Hiding UI Components

To conditionally show or hide UI components, use the rendered property of the component and assign EL expression to it that evaluates to Boolean. If the EL expression evaluates to true, then the component is shown. Consider the following examples:

Note:

The rendered property of the component corresponds to the Show Component option in Oracle Web Composer.

  • To show a UI component if the logged-in user has the System Administrators admin role:

    #{oimcontext.currentUser.roles['SYSTEM ADMINISTRATORS'] != null}

    Similarly, the EL expression can be modified to check if the logged-in user has any other role.

  • To show a UI component if signed-in user has the System Administrator admin role:

    #{oimcontext.currentUser.adminRoles['OrclOIMSystemAdministrator'] != null}

    Similarly, the EL expression can be modified to check if the logged-in user has any other admin role.

  • To show a UI component if the usr_key attribute of the logged-in user is 1:

    #{oimcontext.currentUser['usr_key'] == 1}

  • To show a UI component if the logged-in user's last name is Doe:

    #{oimcontext.currentUser['Last Name'] == 'Doe'}

  • To show a UI component if the logged-in user belongs to the Xellerate Users organization:

    #{oimcontext.currentUser['Organization Name'] == 'Xellerate Users'}

  • To show a UI component if the user's UDF attribute called UDF_NAME equals to UDF_VALUE:

    #{oimcontext.currentUser['UDF_NAME'] == 'UDF_VALUE'}

Note:

"Showing Components Conditionally" describes showing components based on certain conditions by implementing custom Managed Bean.

30.4.3 Showing Request Profiles Conditionally

To show a catalog request profile conditionally:

  1. Login to Oracle Identity Self Service.

  2. Activate a sandbox.

  3. Navigate to the Catalog page.

  4. Click Customize. From the View list, select Source.

  5. Using the source tree, navigate to the iterator component within Request Profiles. The iterator component has panelGroupLayout subcomponent, which represents single request profile.

  6. Assign a Boolean EL expression to the rendered property. This is the Show Component in Web Composer.

    For example, if you want to display a resource profile called Profile to users of the Suppliers organization only, and display any other profile to other users, then use the following expression:

    #{(row.profileName == 'Profile' && oimcontext.currentUser['Organization Name'] == 'Suppliers') || row.profileName != 'Profile'}

    The EL expression is evaluated for every profile which is available. Similarly, you can modify/extend the EL expression to conditionally display any other profile.

30.4.4 Validating Input Data Using ADF Validators

To validate input component data using predefined ADF validators, you must modify the JSFF page fragment and include one of the ADF validators as a child element of input component. Table 30-4 lists the ADF validators:

Table 30-4 ADF Validators

Validator Description

<af:validateByteLength>

Validates the byte length of strings when encoded

<af:validateDateRestriction>

Validates that the date entered is within a given restriction

<af:validateDateTimeRange>

Validates that the date entered is within a given range

<af:validateDoubleRange>

Validates that the date entered is within a given range

<af:validateLength>

Validates that the value entered is within a given length

<af:validateLongRange>

Validates that the value entered is within a given range

<af:validateRegExp>

Validates an expression by using Java regular expression syntax

For example, to validate that the only allowed characters for the User Login attribute are alphanumeric ASCII characters, you can include the following RegExp validator as a child element of the User Login input component:

<af:validateRegExp pattern="[a-zA-Z0-9]*"/>

ADF validators cannot be added directly by using the Web Composer. Instead, you can add another component as a child component of the User Login component, for example, another input text. After that you can export the sandbox containing this change. Finally, update the JSFF page fragment for the form in the exported sandbox, and then import the sandbox.

Note:

"Implementing Custom Field Validation" describes implementing the custom field validator by using custom Managed Bean.

30.4.5 Specifying Required UI Component

To conditionally make an input field required, you can use the required property of the component, and assign it a Boolean EL expression. If the EL expression evaluates to true, then the component is marked as required, and the required validation is triggered.

For example EL expressions, see "Showing or Hiding UI Components".

For more information about making field conditionally mandatory based on the value of another field, see "Setting a Conditional Mandatory Field".

However, this expression takes affect only on the form and does not affect the required validation triggered by Oracle Identity Manager API. See Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for information about Oracle Identity Manager APIs.

30.4.6 Changing Branding and Logo

Customizing or changing UI artifacts, such as logo, buttons, and menu items, can be done at runtime by using Oracle WebCenter Composer.

Note:

The procedure documented in this section is for changing the branding and logo by customizing Oracle Identity Self Service. If you want to customize UI artifacts of the window that opens from the Oracle Identity System Administration, for example, the window that opens when you click System Configuration under System Management, then see "Branding Customization" at the following URL:

http://docs.oracle.com/cd/E21764_01/doc.1111/e14309/uicust.htm#BABFCFID

To change the logo image:

  1. Log in to Oracle Identity Self Service as the system administrator.

  2. Create and activate a sandbox.

    Note:

    Creating and activating a sandbox is mandatory for customizing the UI by using the Web Composer. Without an active sandbox, Oracle Identity Manager does not allow to open any page in customization mode.

  3. Click Customize. The Oracle WebCenter Composer opens. The top of the page shows 'Editing Page'.

  4. From the View list, select Source. The object tree is displayed in the top pane. The object tree shows all the ADF components of the page.

  5. Click the logo. The logo object is selected in the object tree, as shown in Figure 30-3:

    Figure 30-3 The Object Library in WebCenter Composer

    Description of Figure 30-3 follows
    Description of "Figure 30-3 The Object Library in WebCenter Composer"

    The ADF components displayed in the object tree is similar to the structure pane in JDeveloper, as shown in Figure 30-4:

    Figure 30-4 The Structure Pane

    Description of Figure 30-4 follows
    Description of "Figure 30-4 The Structure Pane"

    Note:

    For a complete list of UI components, see Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

  6. Click Edit. The Component Properties dialog box is displayed.

  7. Click the Style tab.

  8. In the Background Image field, enter the path to the logo image that you want to set, for example, url(/identity/faces/images/mylogo.jpg).

    Tip:

    • Place the image files in OIM_ORACLE_HOME/server/apps/oim.ear/xlWebApp.war, and then reference them by an URL, such as url(/xlWebApp/mylogo.png. This must be performed separately in each node in a clustered deployment of Oracle Identity Manager.

    • By default, the Oracle logo is 119x25 pixels. Therefore, you can use a custom logo of the same dimensions. If you want a bigger logo, then it requires CSS changes.

    Figure 30-5 shows the Style tab of the Component Properties dialog box:

    Figure 30-5 The Component Properties Dialog Box

    Description of Figure 30-5 follows
    Description of "Figure 30-5 The Component Properties Dialog Box"

    Tip:

    If you want to specify a font for any ADF component by using the Style tab of the Component Properties dialog box, then ensure that your target browsers and platforms support that specific font name. To look at the supported list for Mozilla Firefox, select Tools, Options, Content, Fonts and Colors. For Microsoft Internet Explorer, select Tools, Internet Options, General, Fonts.

  9. To change the Identity Self Service global banner, click the Identity Self Service text, and repeat steps 5 to 7.

    Tip:

    To change the banner in the Oracle Identity Manager login page, you must open the login page in the customization mode. However, the Customize link is not available in the login page. Therefore, to open the login page in customization mode:

    1. Login to Oracle Identity Self Service as an administrator with privileges to customize the UI.

    2. In an active sandbox, click the Customize link. The Oracle Identity Self Service is in customization mode.

    3. Open another tab in the web browser.

    4. Navigate to http://HOST:PORT/identity/faces/signin. The login page is displayed in customization mode.

  10. Click Save to save the logo and global banner changes.

  11. Click Close to close WebCenter Composer.

  12. Publish the sandbox.

Note:

Runtime UI customization changes the banner text. However, it does not allow you change the browser title, for instance, the title that appears in the browser window, HTML>HEAD>TITLE text or the browser tab title if using tabs.If you want to change the browser text title, then you have to manually edit the value in the resource bundle file OIMUIBundle_*.properties, and redeploy as follows:

oracle.iam.ui.view.war/WEB-INF/lib/adflibCommonUI.jar/oracle/iam/ui/OIMUIBundle_en.properties:

IDENTITY_SELF_SERVICE_TITLE=Identity Self Service

See "Internationalization for Resource Strings" for information about creating and using the custom resource bundles.

30.4.7 Adding a Link

To add a link to Oracle Identity Self Service:

  1. From any page in Oracle Identity Self Service, open WebCenter Composer.

  2. Select the top panel on which you want to include the link. The ADF component is selected in the object tree.

    Figure 30-6 shows the selected top panel and corresponding ADF component in the object tree.

    Figure 30-6 Panel Selection for Adding Link

    Description of Figure 30-6 follows
    Description of "Figure 30-6 Panel Selection for Adding Link"

  3. Click Add Content. The Add Content dialog box is displayed, as shown in Figure 30-7:

    Figure 30-7 The Add Content Dialog Box

    Description of Figure 30-7 follows
    Description of "Figure 30-7 The Add Content Dialog Box"

  4. Search for the link component that you want to add, and click Add in the same row. The link is added to the selected panel.

  5. Click Save to save your changes, and close WebCenter Composer.

    Note:

    For more details, see the following sections:

Oracle Identity Manager allows you to add your own UI or taskflows, such as goLink, commandLink, commandButton, or launch a taskflow.

Perform the following steps to add your custom UI or taskflow:

  1. Write a managed bean and register using adfc-config.xml in oracle.iam.ui.custom-dev-starter-pack.war.

  2. Add a new commandLink or commandButton on the page where you want to display the link or button by using Web Composer.

  3. Set the actionListener property of the link or button component that you added to point to the actionListener method.

  4. Raise the contextual event using the managed bean, which will be handled by Oracle Identity Manager.

Shell launches the taskflow.

30.4.8 Hiding and Deleting an ADF Component

Hiding an ADF component results in the UI artifact being hidden from the user. To hide an ADF component:

  1. In Oracle Identity Self Service, go to the page on which you want to hide a component.

  2. Click Customize to open WebCenter Composer.

  3. From the View menu, select Source. The object tree is displayed.

  4. Click the component on the page that you want to hide. The corresponding ADF component in the object tree is selected.

  5. Right-click the selected ADF component in the object tree, and select Hide.

To delete an ADF component:

  1. From the Oracle Identity Self Service page on which you want to delete any UI component, open Web Composer.

  2. From the View menu, select Source. The object tree is displayed.

  3. Click the component on the page that you want to delete. The corresponding ADF component in the object tree is selected.

  4. Right-click the selected ADF component in the object tree, and select Delete.

30.4.9 Showing and Hiding Attributes

To show or hide attributes in a page:

  1. Go to the page on which you want to show or hide the attribute. For example, navigate to the My Information page in the Oracle Identity Self Service if you want to show or hide the Telephone field.

  2. Click Customize to open Web Composer.

  3. From the View menu, select Source. The object tree is displayed.

  4. Click the region or section that contains the attribute you want to hide, or you want the attribute to be shown.

    The Confirm Task Flow Edit message box is displayed.

  5. Click Edit. The ADF component for the selected region is selected in the object tree.

  6. On the toolbar, click Edit. The Component Properties dialog box is displayed.

  7. Click the Child Components tab. All the UI components of the selected region are displayed. Figure 30-8 shows a sample Child Components tab in the Component Properties dialog box.

    Figure 30-8 The Child Components Tab

    Description of Figure 30-8 follows
    Description of "Figure 30-8 The Child Components Tab"

  8. Select or deselect the checkbox corresponding to the attributes to show or hide the attributes respectively.

  9. Click Apply. The selected attributes are hidden or shown based on your selection.

  10. Click OK, and then click Save on the toolbar.

30.5 Securing UI Components

This section contains the following topics:

30.5.1 Securing a Custom Taskflow Using APM

You can add permissions to custom taskflows by using the Authorization Policy Manager (APM) UI to secure the taskflow. To do so:

  1. Login to Authorization Policy Manager as WebLogic user by navigating to the following URL:

    http://ADMIN_HOST:ADMIN_PORT/apm

  2. Navigate to Applications, OracleIdentityManager, Resource Types. Click Open.

  3. Click New to create a new resource type. Provide following details, and then click Save.

    Display Name: A display name for this resource, for example, ADF Taskflows

    Name: A name for this resource, for example, ADFTaskflows

    Actions: personalize, customize, grant, or view. Click New to add each action.

    Supports Resource Hierarchy: No

    Resource Delimiter: Slash(/)

    Evaluation Logic: Permission Class

    Permission Class: oracle.adf.controller.security.TaskFlowPermission

    Action Name Delimiter: Comma(,)

  4. Navigate to Applications, OracleIdentityManager, Default Policy Domain, Resource Catalog, Resources. Click Open.

  5. Click New to create a new resource. Provide following values, and then click Save.

    Resource Type: Select the resource type created in step 3.

    Display Name: Provide a display name for your custom taskflow.

    Name: Provide the name of the custom taskflow in the following format:

    TASKFLOW_DOCUMENT#TASKFLOW_ID

    For example:

    /WEB-INF/request-approval-details-tf.xml#request-approval-details-tf

    Description: Provide a description for the custom taskflow.

    Note:

    For each custom taskflow, you must create a resource as mentioned in step 5. You can use the same resource type that you created in step 3 for all your custom taskflows.

  6. Navigate to Applications, OracleIdentityManager, Default Policy Domain, Authorization Policies. Click Open.

  7. Select where you want to add the policy for your custom taskflow, for example, Policy for OIM System Admin. Click Open.

  8. Click Add Targets. The Search Targets dialog box is displayed.

  9. Click the Resources tab. Provide the resource type as defined in step 3, and then click Search.

  10. Select the resource created in step 5. Click Add Selected.

  11. Click Add Targets. The resource is added to the Targets table.

  12. Expand the resource that you added to the table. Select the permissions you want to apply to the taskflow.

  13. Click Apply.

30.5.2 Securing a Task Flow Region Using EL Expressions

For each new task flow, there is an entry in the jazn-data.xml file, as shown in the following example:

<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/oracle/iam/ui/catalog/tfs/request-summary-details-tf.xml#request-summary-details-tf</name>
<actions>view</actions>
</permission>

This is the basic level of permission required for any task flow to be visible on the Identity Self Service UI. For advanced permissions dependent on admin roles, you can use EL expressions to enforce functional security.

For securing task flows, the task flow must be used as a region in the parent JSFF file. You can define EL expression for the region so that the task flow can be shown or hidden to the logged-in user based on the user's permissions.

For securing a region, consider the following example:

On the my-access-accounts.jsff page, the details-information-tf task flow is rendered selectively to the users by using the following EL expression:

rendered="# {oimappinstanceAuth.view [bindings.appInstanceKey].allowed}"

Here:

  • oimappinstanceAuth is the mapped name of the ApplicationInstanceAuthz.java authorization bean in the adfc-config.xml file.

  • view is the name of the UIPermission that needs to be checked. The following permission is defined in ApplicationInstanceAuthz.java, which is the actual bean file for reference of oimappinstanceAuth:

    Private UIPermission view = new UIPermission (PolicyConstants.Resources.APPLICATION_INSTANCE.getId(), PolicyConstants.ApplicationInstanceActions.VIEW_SEARCH.getId());

  • appInstanceKey is the ID of the application instance that the user is trying to view, which is passed as a parameter.

30.6 Customizing Oracle Identity Manager Help

Oracle Identity Manager lets you develop and use the following online Help systems in the Oracle Identity Self Service and Oracle Identity System Administration:

30.6.1 Adding Custom Help Topics

In addition to the Oracle Identity Manager help topics, you can also create and use custom help topics.

To view the custom help topics:

  1. Login to Oracle Identity Self Service.

  2. On the navigation bar at the top, click Help. The Oracle Help for the Web window is displayed.

  3. From the Book list, select Custom Help Topics for Oracle Identity Manager.

  4. Expand the contents to view the help topics.

The custom help book is provided as a separate JAR file. This is the OIM_HOME/help/CUSTOMOHW.jar file. You can create your own help topics and custom help book JAR, and then replace the CUSTOMOHW.jar file to display your custom help topics in the UI.

You create the custom help topics by using Oracle Help for the Web (OHW). For detailed information about creating custom OHW help topics, see Oracle Fusion Middleware Developer's Guide for Oracle Help.

After creating the new custom help books, modify the following configuration files in the OIM_HOME/help/ directory to reference the new help books:

  • ohwconfig_identity.xml: Configuration file for custom help topics in Oracle Identity Self Service

  • ohwconfig_sysadmin.xml: Configuration file for custom help topics in Oracle Identity System Administration

Note:

The configuration files are overwritten when you upgrade Oracle Identity Manager, and you must modify the configuration files again to reference the custom help books.

After creating the custom help topics, create the custom help JAR file, and replace the CUSTOMOHW.jar file with the new JAR file. You can now add your custom help topics on the UI pages. The following procedure shows how to add a custom help topic to the Getting Started with Help container of the Home page in the Oracle Identity Self Service:

  1. In the Home page of the Oracle Identity Self Service, click Customize.

  2. Click the Getting Started Help Topics container.

  3. From the View menu, select Source. The object tree is displayed.

  4. Click Add Content. The Add Content dialog box is displayed.

  5. Select Command Image Link, and then click Add in the same row. The selected component is added to the Getting Started Help Topics section.

  6. Click Edit. The Component Properties dialog box is displayed.

  7. Click the Display Options tab.

  8. In the Text field, enter the text for the help topic that will be displayed in the page.

  9. In the Image field, enter the path and file name for the help icon image.

  10. In the Action Listener field, enter the URL with the HelpTopicID of the custom help topic.

  11. Click Apply, and then click OK.

  12. Save and close customization mode. The help topic is added to the Getting Started with Help container of the Home page. Clicking the help topic displays the help topic in the custom help book JAR file.

30.6.2 Adding Inline Help

Oracle Identity Manager does not provide inline help by default. However, you can add your inline help for the various UI components, such as add tooltip text for fields and buttons.

The content for the inline help is picked up from the files in the custom WAR library (oracle.iam.ui.custom-dev-starter-pack.war), such as the /oracle/iam/ui/custom/help/CustomHelpResourceBundle.properties file.

You can change the custom WAR library name. If you do so, then specify the same library name in the entry for the WAR file in Manifest.MF.

You can specify the inline help content through the entries in the CustomHelpResourceBundle.properties file. The entries have a CUSTOMRB prefix, and have any one of the following suffixes:

  • _DEFINITION: This specifies inline help for a field or UI component. For example:

    CUSTOMRB_EMAIL_DEFINITION=Enter your official e-mail ID if available.

    EMAIL is the field name, and the value of the entry is the inline help text displayed on placing your mouse pointer on the field.

  • _INSTURCTIONS: This specified inline help for a page layout. For example:

    CUSTOMRB_MY_INFO_INSTRUCTIONS=Profile update will get reflected post approvals.

    MY_INFO is the page, and the value of the entry is the inline help text displayed on the top of the page.

As an example, the following procedure shows how to add inline help to the Telephone field in the My Information page of Oracle Identity Self Service:

  1. In the Oracle Identity Self Service, navigate to the My Information page, and expand the Basic User Information section.

  2. Click Customize.

  3. From the View menu, select Source. The object tree is displayed.

  4. Click the Telephone field.

  5. Click Edit. The Component Properties dialog box for the Telephone field is displayed.

  6. In the Help Topic ID field, enter the help topic ID of the inline help that you want to associate with the Telephone field, such as CUSTOMRB_TELEPHONE.

    Note that specifying the _DEFINITION suffix is not required.

  7. Click Apply, and then click OK.

  8. Save and close customization mode. When you place the mouse pointer on the Telephone field, the inline help text is displayed.

See Also:

"Displaying Tips, Messages, and Help" on the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework for information about defining tips and messages and providing help information for ADF components

30.7 Customizing the Home Page

The Home page provides you a snapshot of the various functions in the Oracle Identity Self Service. You can personalize the Home page by adding and removing containers, and rearranging containers. See "Personalizing the Home Page" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for details.

When you add a container, you must add UI components to the container to use it. To add containers in the Home page and then add UI components:

Note:

The personalization capabilities, such as adding and removing containers and changing layouts, are not governed by authorization policies. However, the contents available to each user for adding is governed by authorization policies.

  1. Login to Oracle Identity Self Service, and navigate to the Home page.

  2. Click Personalize. The Home is displayed in customization mode with toolbars that consist of icons.

  3. Click the Add Box Above icon on the toolbar. Figure 30-9 shows the Add Box Above icon on the toolbar.

    Figure 30-9 The Add Box Above Icon on the Toolbar

    Description of Figure 30-9 follows
    Description of "Figure 30-9 The Add Box Above Icon on the Toolbar"

    You can click the respective icons to add a box below, right, or left of the container in which you are clicking the icon.

    After clicking the icon, a container is added to the Home page, as shown in Figure 30-10:

    Figure 30-10 A New Container

    Description of Figure 30-10 follows
    Description of "Figure 30-10 A New Container"

  4. Click Add Content. The Add Content dialog box is displayed with the list of homepage task flows that you can add to the container. Figure 30-11 shows the Add Content dialog box.

    Figure 30-11 The Add Content Dialog Box

    Description of Figure 30-11 follows
    Description of "Figure 30-11 The Add Content Dialog Box"

  5. Select the homepage task flow, and click Add. Then, close the Add Content dialog box.

  6. Click Close on the navigation bar at the top to quit customization mode.

30.8 Customizing Challenge Questions

You can customize the number of challenge questions in multiple pages of the UI. To do so, change the value of the PCQ.NO_OF_QUES system property to specify the number of challenge questions that you want to display to the user. In addition, you customize the pages to show or hide the challenge questions that you add or remove respectively.

To set the number of challenge questions:

  1. Login to Oracle Identity System Administration.

  2. On the left pane, under System Management, click System Configuration. The System Configuration tab is displayed in a new window.

  3. Search and open the Number of Questions system property that has the PCQ.NO_OF_QUES keyword.

  4. Change the value from 3 to 5, and click Save.

  5. Close the new window.

  6. In the Oracle Identity System Administration, under Configuration, click Lookups, and search for the Lookup.WebClient.Questions code, as shown in .

    Figure 30-12 The Lookup.Weblciient.Questions Lookup Code

    Description of Figure 30-12 follows
    Description of "Figure 30-12 The Lookup.Weblciient.Questions Lookup Code"

  7. Add additional questions by editing the lookup type.

Note:

You can localize the questions for en_US bundle, as described in "Localizing Challenge Questions and Responses" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

To set challenge questions for the user who is logging in to Oracle Identity Self Service or Oracle Identity System Administration:

  1. Login to Oracle Identity Self Service as the System Administrator, and on home page click on Sandboxes.

  2. On the Home page, click Sandboxes on the upper navigation bar. The Manage Sandboxes page is displayed.

  3. On the toolbar, click Create Sandbox. In the Create Sandbox dialog box, enter a sandbox name, for example ChallengeQ, and click Save and Close.

    Leave the Activate Sandbox check box selected.

  4. On the confirmation dialog box, click OK. The active sandbox is displayed in the table in the Manage Sandboxes page. Close the Manage Sandboxes page.

  5. Open the My Information page. Collapse the Basic Information section, and expand the Challenge Questions section.

  6. Click Customize. Then the toolbar, select View, Source.

  7. Click the third question, and click OK to confirm editing the taskflow.

  8. In the source tree, select the greyed-out panelGroupLayout just after the third question. This contains the fourth question. Right-click this panelGroupLayout, and then select Show Component.

  9. Similarly, show the fifth question.

  10. Click Close on the toolbar.

  11. Repeat steps 4 through 9 for the other three pages on which challenge questions are displayed by pointing the browser to the following URLs:

    • The User Registration page: /identity/faces/register

    • The Forgot Password page: /identity/faces/forgotpassword

    • The Login page when the user logs in for the first time: /identity/faces/firstlogin?action=setchallenges

    Note that there is some variation by design, for example, the question on the Forgot Password page is rendered as outputText rather than a list, as shown in Figure 30-13:

    Figure 30-13 Challenge Question on the Forgot Password Page

    Description of Figure 30-13 follows
    Description of "Figure 30-13 Challenge Question on the Forgot Password Page"

  12. Publish the sandbox and logout.

30.9 Customizing the Transitional UI

In the transitional UI pages of the Identity Self Service, when you click a menu item to perform tasks, such as managing access policies, a search page is displayed. For example, when you click the Manage link under the Access Policies menu item, the Manage Access Policies page is displayed with two drop-down menus for searching access policies. You can customize the number of drop-down menus, and what the items in the drop-down menus are.

When the search results display, you can determine the maximum number of rows in the results table displayed on each page. After a user selects an item from the results table, a detail page is displayed such as the Resource Detail page. The detail page contains an additional details menu. You can customize the items in these menus.

This section contains the following topics:

30.9.1 Customizing Search Drop-Down Item

Use the Design Console to change the lookup codes for search pages and additional details. To customize drop-downs:

  1. Log in to the Design Console.

  2. Open the Lookup Definition form by navigating to Administration, then to Lookup Definition.

  3. Search to locate the desired lookup definition.

    Tip:

    For your search criteria, use lookup.webclient* search to find the search pages, or *additional_details to find the additional details.

  4. Make the desired changes to the lookup codes to set the options displayed in the drop-down menu for each search page.

    • The Code Key is the metadata for each column.

    • The Decode value is what is displayed in the Identity Self Service or Identity System Administration.

    • The order in which the items appear in the Code Key list are the order they appear in the drop-down list in the Identity Self Service. If you delete an entry and add it back, it is displayed last in the list.

  5. Save your changes.

30.9.2 Customizing Number of Search Drop-Down Items and Search Results

To change the number of drop-down menus, and the maximum number of search results on each page, edit the xlDefaultAdmin.properties file.

To set the number of drop-down menus:

  1. Open the xlDefaultAdmin.properties file.

  2. Locate the property from Table 30-5, and edit it as required.

    Table 30-5 Properties that Determine the Number of Menus on a Search Page

    Property Name Default Page

    global.property.numsearchaccesspolicyfields

    2

    Access Policies

    global.property.numsearchresourcefields

    2

    Search Resources

    global.property.numsearchattestationprocessfields

    3

    Attestation Process

  3. To change the maximum number of search results on each page, change the value of the property global.displayrecordNum.value to the desired value. The default value is 10.

  4. Save the file.

  5. Restart Oracle Identity Manager.

30.10 Developing Managed Beans

You can develop and use managed JAVA beans to implement advanced customization in Oracle Identity Manager. The beans are of the following types:

  • Request beans: New instance of the bean is created for every request.jsff component bindings, and listeners are usually bound to request beans.

  • State beans: Beans holding the state of the application, user session, or a particular flow. Values of components, such as af:inputText, can be bound to state beans. State beans must be serializable (implement java.io.Serializable) as ADF serializes/deserializes these beans between requests.

This section describes how to develop managed beans in the following topics:

30.10.1 Setting Up the ViewController Project

Managed beans are created in a ViewController project. All your custom taskflows, pages, and managed beans must be present in the ViewController project.

To setup the ViewController project:

  1. Create a new JDeveloper application. To do so:

    1. Start JDeveloper.

    2. Select File, New.

    3. Select Generic Application, and then click OK.

    4. Provide the application name and directory, and then click Finish. The application is created using a sample project.

    5. To delete the sample project, right-click the project, and select Delete.

  2. Setup the ViewController project. To do so:

    1. Select File, New.

    2. Find and select ADF ViewController Project, and then click OK.

    3. Provide the project name, for example CustomUI, and project directory, and then click Next.

    4. Enter the default package name as oracle.iam.ui.custom, and then click Finish. The new project is created.

  3. Add Oracle Identity Manager libraries to the project classpath. To do so:

    1. Right-click the new project, and select Project Properties.

    2. On the left navigation bar, select Libraries and Classpath.

    3. Click Add Library.

    4. Click Load Dir, provide the path as IDM_HOME/server/jdev.lib, and then click OK.

    5. From the list of libraries, select the following:

      • OIM View Shared Library

      • OIM Model Shared Library

      • OIM Client Library

    6. Click OK.

  4. Define the deployment profile for the newly created ViewController project. To do so:

    1. Right-click the project, and select Project Properties.

    2. On the left navigation bar, select Deployment.

    3. Delete any existing deployment profiles.

    4. Click New, and select ADF Library JAR File as the archive type.

      Note:

      The ADF Library JAR File and JAR File archive types are different. Make sure that you select the ADF Library JAR File archive type.

    5. Provide and confirm the archive name, such as adflibCustomUI, and then click OK.

Your ViewController project setup is complete. You can now start adding custom taskflows, pages, and managed beans.

30.10.2 Setting Up a Model Project

All your custom EOs/VOs and classes interacting directly with Oracle Identity Manager APIs must be present in a model project. To setup the model project:

  1. Click File, New.

  2. Find and select ADF Model Project, and then click OK.

  3. Provide the Project Name, for example CustomModel, and Project Directory, and then click Next.

  4. Enter Default Package name as oracle.iam.ui.custom, and then click Finish. The new peoject is created.

  5. Add Oracle Identity Manager libraries to the project classpath:

    1. Right-click the project, and select Project Properties.

    2. On the left navigation bar, select Libraries and Classpath.

    3. Click Add Library.

    4. Click Load Dir, provide the path as IDM_HOME/server/jdev.lib, and then click OK.

    5. From the list of libraries select the following:

      • OIM Model Shared Library

      • OIM Client Library

    6. Click OK.

  6. Define the deployment profile for the newly created model project. To do so:

    1. Right-click the project, and select Project Properties.

    2. On the left navigation bar, select Deployment.

    3. Delete any existing deployment profiles.

    4. Click New, and select ADF Library JAR File as the archive type.

      Note:

      The ADF Library JAR File and JAR File archive types are different. Make sure that you select the ADF Library JAR File archive type.

    5. Provide and confirm the archive name, such as adflibCustomModel, and then click OK.

Your model project setup is complete. You can now start adding custom EOs, VOs, and classes for interacting with Oracle Identity Manager APIs.

30.10.3 Adding Custom Managed Bean

To add your custom managed bean:

  1. Right-click the ViewController project, and select New.

  2. Select the Java Class category.

  3. Provide the class name, for example CustomReqBean or CustomStateBean, and the package name.

  4. After creating the class, to register it with a taskflow:

    1. If you are developing your own bounded task flow, then navigate to your task flow definition file, and open it. Otherwise, locate the adfc-config.xml file in your ViewController project, and open it.

    2. Click the Overview tab, and select Managed Beans.

    3. Add a new managed bean entry. To do so:

      i) Provide managed bean name, for example customReqBean or customStateBean. This is the name that you will later use to refer to an instance of your bean.

      ii) Provide the managed bean class name.

      iii) Provide the scope. For request beans use backingBean scope. For state beans, use pageFlow scope.

      Note:

      • The pageFlow scope beans are visible only in the taskflow for which they are defined.

      • To refer to your managed bean from JSFF/taskflow definition or other places, you can use EL expression. For example, if you register your bean under the name customReqBean and put the bean to backingBean scope, then you can reference your bean by using the following EL expression:

        #{backingBeanScope.customReqBean}

        If you put the bean to pageFlow scope, you can reference your bean by using the following EL expression:

        #{pageFlowScope.customStateBean}

30.10.4 Deploying Custom Code to Oracle Identity Manager

To deploy an ADF library JAR file produced by your custom model or ViewController projects:

  1. Locate the oracle.iam.ui.custom shared library, which is oracle.iam.ui.custom-dev-starter-pack.war. The shared library is in the IDM_HOME/server/apps/ directory.

  2. Repackage the WAR and include your ADF libraries in WEB-INF/lib/.

  3. Redeploy the shared library.

30.10.5 Using Managed Beans

This section provides the following use cases for developing managed beans to customize Oracle Identity Manager interface:

Note:

The examples in this section use the FacesUtils class. For information about this class, see "The FacesUtils Class".

30.10.5.1 Showing Components Conditionally

You can show or hide certain fields conditionally based on the values of other fields. For example, to show the Contact Information panel on the Create User page only when the User Type is Full-Time Employee, perform the following steps:

  1. In your custom request bean, define properties for component bindings of the User Type field and any parent component of the Contact Information panel, for example, the form root panel. To do so, use the following code:

    private UIComponent rootPanelPGL;
    private UIComponent userTypeSOC;
        
    public void setRootPanelPGL(UIComponent rootPanelPGL) {
        this.rootPanelPGL = rootPanelPGL;
    }
 
    public UIComponent getRootPanelPGL() {
        return rootPanelPGL;
    }
 
    public void setUserTypeSOC(UIComponent userTypeSOC) {
        this.userTypeSOC = userTypeSOC;
    }
 
    public UIComponent getUserTypeSOC() {
        return userTypeSOC;
    }

  2. Create or extend existing valueChangeListener that will be invoked when user selects the new value in the User Type list. To do so, use the following code:

    Note:

    The listener will refresh the form.
    public void valueChangeListener(ValueChangeEvent valueChangeEvent) {        
        if (valueChangeEvent.getSource().equals(userTypeSOC)) {   
            // refresh form
            FacesUtils.partialRender(rootPanelPGL);
        }
    }

  3. Create a method that returns boolean value. The method will determine if the Contact Information panel is to be displayed when the page is rendered. In this example, the Contact Information panel will be shown if the User Type is Full-Time Employee.

    The method is as follows:

    private static final String USER_TYPE_ATTRIBUTE = "usr_emp_type__c";
    
    public boolean isFullTimeEmployeeUserTypeSelected() {
        // return true if value of "usr_emp_type__c" binding attribute equals to "Full-Time"
        // "usr_emp_type__c" binding attribute is used to display value of User Type in the User Type drop-down        
        return "Full-Time".equals(FacesUtils.getListBindingValue(USER_TYPE_ATTRIBUTE, String.class));    
    }

  4. To bind the code with JSFF:

    1. Set component bindings for the User Type list and root panel components to point to the properties that you defined.

    2. Define the valueChangeListener for the User Type list.

      Note:

      Make sure that the autosubmit property is set to true for the User Type list.

    3. Set EL expression for the rendered property, which is Show Component in Web Composer, on the Contact Information panel to point to the isFullTimeEmployeeUserTypeSelected() method defined in step 3.

30.10.5.2 Prepopulating Fields Conditionally

You prepopulate certain fields based on the values of other fields. For example, to prepopulate values in the User Login and E-mail fields on the Create User page based on the values of the First Name and Last Name fields, perform the following steps:

  1. In your custom request bean, define properties for component bindings of First Name and Last Name fields and any parent component of the User Login and E-mail fields, for example, form root panel. To do so, use the following code:

    private UIComponent firstNameIT;
    private UIComponent lastNameIT;
    private UIComponent rootPanelPGL;
    
    public void setFirstNameIT(UIComponent firstNameIT) {
        this.firstNameIT = firstNameIT;
    }
 
    public UIComponent getFirstNameIT() {
        return firstNameIT;
    }
 
    public void setLastNameIT(UIComponent lastNameIT) {
        this.lastNameIT = lastNameIT;
    }
 
    public UIComponent getLastNameIT() {
        return lastNameIT;
    }
 
    public void setRootPanelPGL(UIComponent rootPanelPGL) {
        this.rootPanelPGL = rootPanelPGL;
    }
 
    public UIComponent getRootPanelPGL() {
        return rootPanelPGL;
    }

  2. Create or extend existing valueChangeListener that will be invoked when the user updates the First Name or Last Name fields. To do so, use the following code:

    Note:

    The listener will update User Login and E-mail accordingly and refresh the form.
    private static final String USER_LOGIN_ATTRIBUTE = "usr_login__c";
    private static final String EMAIL_ATTRIBUTE = "usr_email__c";
    private static final String LAST_NAME_ATTRIBUTE = "usr_last_name__c";
    private static final String FIRST_NAME_ATTRIBUTE = "usr_first_name__c";
    
    public void valueChangeListener(ValueChangeEvent valueChangeEvent) {
        if (valueChangeEvent.getSource().equals(firstNameIT)) {
            // get new value of first name from the event
            String firstName = (String)valueChangeEvent.getNewValue();            
            // get existing value of last name through binding
            String lastName = FacesUtils.getAttributeBindingValue(LAST_NAME_ATTRIBUTE, String.class);
            setUserLoginAndEmail(firstName, lastName);
        } else if (valueChangeEvent.getSource().equals(lastNameIT)) {
            // get existing value of first name through binding
            String firstName = FacesUtils.getAttributeBindingValue(FIRST_NAME_ATTRIBUTE, String.class);            
            // get new value of last name from the event
            String lastName = (String)valueChangeEvent.getNewValue();
            setUserLoginAndEmail(firstName, lastName);
        }
        // refresh form
        FacesUtils.partialRender(rootPanelPGL);
    }
 
    private void setUserLoginAndEmail(String firstName, String lastName) {
        StringBuilder sb = new StringBuilder();        
        if (firstName != null) {
            sb.append(firstName);
        }
        if (firstName != null && !firstName.isEmpty() && lastName != null && !lastName.isEmpty()) {
            sb.append(".");
        }
        if (lastName != null) {
            sb.append(lastName);
        }
        String userLogin = sb.toString();
        // set new value for User Login and E-mail through binding
        FacesUtils.setAttributeBindingValue(USER_LOGIN_ATTRIBUTE, userLogin);
        FacesUtils.setAttributeBindingValue(EMAIL_ATTRIBUTE, userLogin + "@acme.com");    
}

  3. Add the code to the JSFF. To do so:

    1. Set the component bindings for First Name, Last Name, and root panel to point to the properties that you defined.

    2. Define valueChangeListener for First Name and Last Name input texts, and make sure that the autosubmit property is set to true on both input texts.

30.10.5.3 Setting a Conditional Mandatory Field

You can make a field conditionally mandatory based on the value of another field. For example, to make the Manager field on the Create User page mandatory only if the User Type is Intern, perform the following steps:

Note:

Enforcing field validation cannot be performed by setting the required property in Web Composer. You must develop a managed bean to perform field validation, as described in this section.

  1. In your custom request bean, define properties for component bindings of the User Type field and any parent component of Manager field, for example, form root panel. To do so, use the following code:

    private UIComponent rootPanelPGL;
    private UIComponent userTypeSOC;
        
    public void setRootPanelPGL(UIComponent rootPanelPGL) {
        this.rootPanelPGL = rootPanelPGL;
    }
 
    public UIComponent getRootPanelPGL() {
        return rootPanelPGL;
    }
 
    public void setUserTypeSOC(UIComponent userTypeSOC) {
        this.userTypeSOC = userTypeSOC;
    }
 
    public UIComponent getUserTypeSOC() {
        return userTypeSOC;
    }

  2. Create or extend existing valueChangeListener that will be invoked when user selects new value in the User Type list. To do so, use the following code:

    Note:

    The listener will refresh the form.
    public void valueChangeListener(ValueChangeEvent valueChangeEvent) {        
        if (valueChangeEvent.getSource().equals(userTypeSOC)) {   
            // refresh form
            FacesUtils.partialRender(rootPanelPGL);
        }
    }

  3. Create a method that returns boolean value. The method determines whether or not the field is mandatory. In this example, the Manager field will be marked as mandatory if User Type is Intern.

    The method is as follows:

        public boolean isInternUserTypeSelected() {
        // return true if value of "usr_emp_type__c" binding attribute equals to "Intern"
        // "usr_emp_type__c" binding attribute is used to display value of User Type in the User Type drop-down
return "Intern".equals(FacesUtils.getValueFromELExpression("#{bindings.usr_emp_type__c.attributeValue}"));
    }

  4. Add the code to the JSFF. To do so:

    1. Set component bindings for the User Type list and root panel components to point to the properties you defined.

    2. Define valueChangeListener for the User Type list. Make sure that the autosubmit property is set to true for the User Type list.

    3. Set EL expression for the required property on the Manager field to point to the isInternUserTypeSelected() method defined is step 3.

30.10.5.4 Implementing Custom Field Validation

You can introduce a custom field validator. For example, you can implement the following validations for the Start Date and End Date fields on the Account Effective Dates panel of the Create User page:

  • Start Date cannot be after End Date.

  • The interval between Start Date and End Date cannot exceed 180 days for Contractors.

To implement custom validators:

  1. In your custom request bean, define properties for component bindings of the Start Date and End Date fields, as shown:

    private UIComponent startDateID;
private UIComponent endDateID;
 
public void setStartDateID(UIComponent startDateID) {
    this.startDateID = startDateID;
}
 
public UIComponent getStartDateID() {
    return startDateID;
}
 
public void setEndDateID(UIComponent endDateID) {
    this.endDateID = endDateID;
}
 
public UIComponent getEndDateID() {
    return endDateID;
}

  2. Create or extend existing validator that will be invoked when the user selects new value for the Start Date or End Date field. The validator generates an error message when validation fails and attaches it to the field being updated. To do so, use the following code:

    private static final String START_DATE_END_DATE_VALIDATION_MSG = "Start Date - End Date interval cannot exceed 180 days for Contractors.";
    private static final String START_DATE_AFTER_END_DATE_VALIDATION_MSG = "Start Date cannot be after End Date.";
 
    private static final String USER_TYPE_ATTRIBUTE = "usr_emp_type__c";
    private static final String START_DATE_ATTRIBUTE = "usr_start_date__c";
    private static final String END_DATE_ATTRIBUTE = "usr_end_date__c";
    
    public void validator(FacesContext facesContext, UIComponent uiComponent, Object object) {
        if (uiComponent.equals(startDateID)) {
            // get value of End Date through binding
            oracle.jbo.domain.Date jboEndDate = FacesUtils.getAttributeBindingValue(END_DATE_ATTRIBUTE, oracle.jbo.domain.Date.class);
            // only validate if both Start Date and End Date are set
            if (jboEndDate != null) {
                // value of Start Date is passed to validator
                Date startDate = ((oracle.jbo.domain.Date)object).getValue();
                Date endDate = jboEndDate.getValue();
                validateStartDateEndDate(facesContext, uiComponent, startDate, endDate);
            }
        } else if (uiComponent.equals(endDateID)) {
            // get value of Start Date through binding
            oracle.jbo.domain.Date jboStartDate = FacesUtils.getAttributeBindingValue(START_DATE_ATTRIBUTE, oracle.jbo.domain.Date.class);
            // only validate if both Start Date and End Date are set
            if (jboStartDate != null) {
                Date startDate = jboStartDate.getValue();
                // value of End Date is passed to validator
                Date endDate = ((oracle.jbo.domain.Date)object).getValue();
                validateStartDateEndDate(facesContext, uiComponent, startDate, endDate);
            }
        }
    }
 
    private void validateStartDateEndDate(FacesContext facesContext, UIComponent uiComponent, Date startDate, Date endDate) {
        Date startDatePlus180Days = new Date(startDate.getTime() + 180L * 24 * 60 * 60 * 1000);
        if (startDate.after(endDate)) {
            // queue error message for the component which is being validated (either Start Date or End Date)
            facesContext.addMessage(uiComponent.getClientId(facesContext),
                                    new FacesMessage(FacesMessage.SEVERITY_ERROR, START_DATE_AFTER_END_DATE_VALIDATION_MSG, null));
        } else if (isContractorUserTypeSelected() && startDatePlus180Days.before(endDate)) {
            // queue error message for the component which is being validated (either Start Date or End Date)
            facesContext.addMessage(uiComponent.getClientId(facesContext),
                                    new FacesMessage(FacesMessage.SEVERITY_ERROR, START_DATE_END_DATE_VALIDATION_MSG, null));
        } else {
            // re-render -- in case there was an error message in queue for any of the two components it will be released
            FacesUtils.partialRender(startDateID);
            FacesUtils.partialRender(endDateID);
        }
    }
 
    public boolean isContractorUserTypeSelected() {
        // return true if value of "usr_emp_type__c" binding attribute equals to "Contractor"
        // "usr_emp_type__c" binding attribute is used to display value of User Type in the User Type drop-down
        return "Contractor".equals(FacesUtils.getListBindingValue(USER_TYPE_ATTRIBUTE, String.class));
    }

  3. Bind the code to the JSFF. To do so:

    1. Set component bindings for the Start Date and End Date fields to point to the properties that you defined.

    2. Define EL expression for validator property on Start Date and End Date fields to point to the validator method that you defined in step 2.

30.10.5.5 Implementing Custom Cascading LOVs

Cascading LOVs are LOV components for which the list of values in one component is dependent on the currently selected value in another component. For example, based on the selected value in the User Type list on the Create User page, you might want to display the Job Code list or another LOV component whose list of values is dependent on the currently selected value in the User Type list.

The following are the high-level guidelines to implement custom cascading LOVs:

  1. Define component binding for the User Type field and any parent component of Job Code, for example, form root panel.

  2. Implement the model for Job Code LOV component by ensuring the following:

    • The model must take into account the current value of the User Type field.

    • For af:selectOneChoice, you must implement a method that returns List<javax.faces.model.SelectItem>.

    • For af:inputListOfValues, you must implement a method that returns an instance of oracle.adf.view.rich.model.ListOfValuesMode.

    See Also:

    "Using List-of-Values Components" in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework for information about using a LOV component to display a model-driven list of objects from which a user can select a value

  3. Implement valueChangeListener for the User Type field. Set the autosubmit property to true for the User Type field.

    valueChangeListener must update model of Job Code LOV component with the current value of the User Type field. In addition, valueChangeListener must re-render the form so that Job Code LOV component is updated with the current list of values.

30.10.5.6 Customizing Forms By Using RequestFormContext

RequestFormContext is a bean available in the pageFlowScope of entity form details taskflow. The entity forms include user form, application instance form, role form, and entitlement form. The instance provides various context information. Using this context information, you can customize various forms based on specific business requirements.

You can get an instance of the class by using Java code, as shown:

RequestFormContext.getCurrentInstance();

You can also get an instance of the class by using EL, as shown:

#{pageFlowScope.requestFormContext}

RequestFormContext provides the following context information:

  • operation: The operation that is being performed on the entity. The possible values are CREATE and MODIFY.

  • actionType: The action that is being performed by the user when the entity form is displayed. The possible values are: APPROVAL, FULFILL, REQUEST, VIEW, SUMMARY.

  • bulk: Whether or not it is a bulk operation.

  • beneficiaryIds: The list of beneficiary or target user IDs. For example, if you are requesting an application instance for the user John Doe, then the list contains the user ID of John Doe.

  • cartItemIds: The list of cart item IDs. For example, if you are requesting an application instance for a user, then the list contains the application instance ID that is being requested.

  • requestEntityType: The entity type being requested, which is any one of ROLE, ENTITLEMENT, APP_INSTANCE, USER.

  • requestEntitySubType: The subtype of entity being requsted. For example, when requesting for an application instance, the requestEntitySubType is the application instance key.

  • instanceKey: The key of the instance being modified.

The following is an example usage of the RequestFormContext:

You might want to add new Prepopulate button to the Create Application Instance form, and make the button visible only when there is only one target user. When the button is clicked, some of the application instance fields, such as User Login, First Name, and Last Name) will be prepopulated based on the current target user. To achieve this, perform the following steps:

  1. In your custom request bean, define properties for component bindings of the Prepopulate button and the form root panel, as shown:

    private UIComponent rootPanel;
    private UIComponent prepopulateButton;
        
    public void setRootPanel(UIComponent rootPanel) {
        this.rootPanel = rootPanel;
    }
 
    public UIComponent getRootPanel() {
        return rootPanel;
    }
 
    public void setPrepopulateButton(UIComponent prepopulateButton) {
        this.prepopulateButton = prepopulateButton;
    }
 
    public UIComponent getPrepopulateButton() {
        return prepopulateButton;
    }

  2. Implement an actionListener that will be invoked when the Prepopulate button is clicked. The actionListener uses the target user ID and fetches user data, such as First Name and Last Name, by using Oracle Identity Manager API. Use the fetched data, and set certain application instance attributes through attribute binding, and finally refresh the form so that new values are displayed. The actionListener is as shown:

    public void actionListener(ActionEvent e) {
        if (e.getSource().equals(prepopulateButton)) {
            RequestFormContext requestFormContext = RequestFormContext.getCurrentInstance();
            List<String> beneficiaryIds = requestFormContext.getBeneficiaryIds();
            if (beneficiaryIds.size() == 1) {
                // prepopulate fields based on selected beneficiary
                User user = getUser(beneficiaryIds.get(0));
                FacesUtils.setAttributeBindingValue(ACCOUNT_LOGIN_ATTRIBUTE, user.getLogin());
                FacesUtils.setAttributeBindingValue(ACCOUNT_ID_ATTRIBUTE, user.getId());
                FacesUtils.setAttributeBindingValue(FIRST_NAME_ATTRIBUTE, user.getFirstName());
                FacesUtils.setAttributeBindingValue(LAST_NAME_ATTRIBUTE, user.getLastName());
            }
        }
        FacesUtils.partialRender(rootPanel);
    }
 
    private User getUser(String userId) {
        UserManager userManager = OIMClientFactory.getUserManager();
        try {
            return userManager.getDetails(userId, null, false);
        } catch (NoSuchUserException e) {
            throw new RuntimeException(e);
        } catch (UserLookupException e) {
            throw new RuntimeException(e);
        }
    }

  3. Create a method that returns Boolean value. The method determines if the Prepopulate button is to be displayed when the form is rendered. In this example, the Prepopulate button will be displayed when the number of target users is equal to 1. The method is as follows:

    public boolean isPrepopulateButtonRendered() {
        RequestFormContext requestFormContext = RequestFormContext.getCurrentInstance();
        return requestFormContext.getActionType() == RequestFormContext.ActionType.REQUEST && requestFormContext.getBeneficiaryIds().size() == 1;
    }

  4. Bind the code with JSFF. To do so:

    1. Add a Prepopulate button to the Create Application Instance form.

    2. Set bindings for the Prepopulate button and the root panel.

    3. Set the Prepopulate button actionListener property to point to the actionListener method implemented in step 2.

    4. Set the rendered property to point to the isPrepopulateButtonRendered() method implemented in step 3.

30.10.5.7 Overriding the Submit Button in Request Catalog

Can override the Submit button in the request catalog and execute additional logic based on your requirements. For example, to add additional check for number of target users or beneficiaries when submitting a request, and allow submitting the request when the number of beneficiaries is not more than five, perform the following steps:

  1. Implement actionListener that will override the original Submit button.

    The actionListener will be invoked when the user clicks the Submit button. The actionListener performs the extra check and either display error messages or executes the original actionListener bound to the Submit button. Original Submit button actionListener can be executed using the following EL expression:

    #{backingBeanScope.cartReqBean.submitActionListener}

    The actionListener code is as shown:

    public void submitButtonActionListener(ActionEvent e) {
        // only submit request if there is no more than 5 beneficiaries
        Boolean moreThanFiveTargetUsers = FacesUtils.getValueFromELExpression("#{backingBeanScope.cartReqBean.targetUserSize > 5}", Boolean.class);
        if (moreThanFiveTargetUsers) {
            // display error message
            FacesMessage fm = new FacesMessage();
            fm.setSeverity(FacesMessage.SEVERITY_ERROR);
            fm.setSummary(MORE_THAN_FIVE_TARGET_USERS_MSG);
            FacesUtils.showFacesMessage(fm);
        } else {
            // execute original submit button action listener
            MethodExpression originalActionListener =
                FacesUtils.getMethodExpressionFromEL("#{backingBeanScope.cartReqBean.submitActionListener}", null, new Class[] { ActionEvent.class });
            originalActionListener.invoke(FacesUtils.getELContext(), new Object[] { e });
        }    
    }

  2. Update the Submit button actionListener property to point to the new actionListener implementation.

30.10.5.8 Developing Home Page Portlets

Hompage portlet is a regular bounded taskflow that can be added to the user's Home page in Oracle Identity Self Service. Bounded taskflows must be created in ViewController projects. For information about setting up the ViewController project, see "Setting Up the ViewController Project". For information about adding a custom managed bean, see "Adding Custom Managed Bean".

See Also:

"Creating ADF Task Flows" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework for information about developing ADF taskflows

After developing the bounded taskflow, you must deploy it. For information about deploying the bounded taskflow, see "Deploying Custom Code to Oracle Identity Manager".

Every new taskflow must be granted a permission to make it visible in the Identity Self Service. See "Securing a Task Flow Region Using EL Expressions" for details.

The final step in developing Home page portlets is updating the resource catalog for the Home page. This allows the users to add the portlet to the homepage.To update the Home page resource catalog:

  1. Locate the oracle.iam.ui.custom shared library, which is oracle.iam.ui.custom-dev-starter-pack.war. This is available in the DM_HOME/server/apps/ directory.

  2. Unpack the WAR and locate the oracle/adf/rc/metadata/custom-catalog.xml file.

  3. Update the file and include reference to your newly added bounded taskflow. The entry looks similar to the following:

    <resource id="helloWorld" name="Hello World"
description="Hello World Taskflow Reference"
repository="application.classpath"
path="adflibHomepagePortletsUI.jar/ADF_TaskFlow/WEB-INF+oracle+iam+ui+sample+homepage+tfs+hello-world-tf.xml#hello-world-tf">
<attributes>
<attribute value="coreDefault" attributeId="attr.background" isKey="false"/>
</attributes>
</resource>

    Note:

    Make sure that the format of the path property is correct. The format must follow the same pattern as shown in step 3. In addition, ensure that the value of the repository property is application.classpath. For more information about the format of this file, see "resource" of the "Catalog Definition Attributes" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

  4. Redeploy the shared library.

30.10.5.9 Launching Taskflows

You can launch a taskflow in the Self Service interface. For example, if you want to launch a tab with a bounded taskflow running in it, then perform the following steps:

  1. In your custom request bean, create the following actionListener that will be invoked when the user clicks a link or button:

    public void actionListener(ActionEvent e) {
        // launch homepage taskflow in a tab
        // you can launch the taskflow in a popup also by setting inDialog to true
        FacesUtils.launchTaskFlow("home", "/WEB-INF/oracle/iam/ui/homepage/home/tfs/home-tf.xml#home-tf",
                       "Home", "/images/home.png", null, "helpTopicId", false, new HashMap<String, Object>());
    }

    Here, the second parameter that is passed to FacesUtils.launchTaskFlow, which is /WEB-INF/oracle/iam/ui/homepage/home/tfs/home-tf.xml#home-tf, is the taskflow ID and must match with the existing taskflow ID. Taskflow ID consists of the path to the taskflow definition file, "#", and the value of the ID attribute of the task-flow-definition element within the taskflow definition file, for example, <task-flow-definition id="home-tf">.

  2. Add a new commandLink or commandButton to the page on which you want to display the link or button by using Web Composer.

  3. Set the actionListener property of the link or button component that you added to point to the actionListener method.

Note:

The page definition of the JSFF page containing the link or button component must have the following eventBinding: 
<eventBinding id="raiseTaskFlowLaunchEvent">
      <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
        <event name="oracle.idm.shell.event.TaskFlowLaunchEvent"/>
      </events>
    </eventBinding>

Existing Oracle Identity Manager pages already contain this eventBinding. You must define this eventBinding for JSFF pages that you build.

30.10.5.10 Creating an External Link

To add a link or button that redirects the user to a certain URL:

  1. In your custom request bean, create the following actionListener that will be invoked when the user clicks a link or button:

    public void actionListener(ActionEvent e) {
        FacesUtils.redirect("http://www.oracle.com");
    }

  2. Add a new commandLink or commandButton to the page on which you want to display the link or button by using Web Composer.

  3. Set the actionListener property of the link or button component that you added to point to the actionListener method.

30.11 UI Customization Best Practice

When creating a sandbox, create it with a detailed description and list all the entities for which you are creating the sandbox. For example, if you are creating an application instance, note that this sandbox is created for application instance creation. When the application instance is created, publish the sandbox, and then go to Identity Self Service to create another sandbox to perform the UI customization. This is to avoid issues when two or more users create different sandboxes to create the same entity (application instance in this example) and try to publish it at different times.

30.12 UI Customization Known Issue

If you are unable to login to Oracle Identity System Administration after customizing the interface and publishing the sandbox, then perform the following steps:

  1. Login to Oracle Enterprise Manager.

  2. In Application Deployments, select oracle.iam.ui.console.self-service.ear.

  3. On the top-right of the page, select Application Deployment, and then select MDS Configuration from the list.

  4. At the bottom of the screen, select Runtime MBean Browser under the Advanced Configuration section. The right side of the screen refreshes.

  5. Click the Operations tab.

  6. Scroll down and identify the listMetadataLabels MBean operation and invoke it. Select the MBean operation that does not take any parameters. Select the sandbox precreate that you want to restore, and copy it to the clipboard.

    For example, the value you copy can be similar to: Creation_IdM_test_09:25:00.

  7. Click Return to go back to the Operation tab.

  8. Find the promoteMetadataLabel MBean operation.

  9. Invoke the promoteMetadataLabel MBean operation, and enter the value that you copied in step 6.

  10. Restart Oracle Identity Manager.

  11. Login to Oracle Identity System Administration.