Customizing the Interface

19 Customizing the Interface

You can customize various aspects of the user interfaces available in Oracle Identity Manager.

This chapter describes how to customize the UI. It contains the following topics:

Note:

This release of Oracle Identity Manager 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.

19.1 Managing Sandboxes

All customizations and form management are performed in a sandbox.

This section describes the concepts related to sandbox and how to manage sandboxes. It contains the following topics:

19.1.1 Understanding Sandbox Operations

A sandbox allows you to isolate and experiment with customizations without affecting the environment of other users.

Any user-interface 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 UI metadata objects, for example pages and forms, are stored only in the sandbox. 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.
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, 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.
Publish in bulk and sequence: If you have stored different types of changes in multiple sandboxes, then you can publish more than one or all the sandboxes in bulk to merge all the changes to the mainline and make them available to other users. While publishing the sandboxes in bulk, you can specify the sequence in which the sandboxes are to be published. See Publishing Sandboxes in Bulk and Sequence for the procedure to publish sandboxes in bulk and sequence.
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 the versioning system. 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.

19.1.2 Handling Concurrency Conflicts

Multiple users can customize an application by using sandboxes, which might result in concurrency conflicts.

This section describes concurrency conflicts and how to handle them. It contains the following topics:

19.1.2.1 Understanding Concurrency Conflicts

When multiple users work to customize an application by using sandboxes, 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.

19.1.2.2 Guidelines to Avoid Conflicts When Multiple Users Work in a Single Sandbox

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.

19.1.2.3 Guidelines to Avoid Conflicts When Multiple Users Work in Multiple Sandboxes

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.

19.1.2.4 Troubleshooting Concurrency Issues

Table 19-1 lists the issues that you might encounter if there are concurrency conflicts in the sandbox usage and the possible solutions.

Table 19-1 Troubleshooting Concurrency Issues

Example Scenario	Problem	Solution
Working on multiple sandboxes intended for publishing concurrently: Create sandbox S1, create sandbox S2, make changes to S2, publish S2, make changes to S1, and publish S1.	When you try to publish S1, an error is thrown.	Create a new sandbox and redo the changes.
Migrating sandboxes out-of-order: In environment 1, create sandbox S1, make changes to S1, export and publish S1. Repeat the same for S2. In environment 2, import S2, publish S2. Then, import S1,and publish S1. Sandboxes S1 and S2 are published in different order.	If there is any overlap between S1 and S2, for example both sandboxes updated the same MDS document), then changes made as part of S2 are overwritten by S1. For example, if AD connector form is created as part of S1 and EBS connector form is created as part of S2, then there will be overlap in CatalogAM.xml.xml and BizEditor resource bundle file. After the migration, both CatalogAM.xml.xml and BizEditor resource bundle only contain changes for AD Connector developed as part of S1.	Publish the sandboxes in correct order. You will be able to republish them.
Skipping sandbox during migration: In environment 1, create sandbox S1, make changes to S1, export and publish S1. Repeat the same for S2. In environment 2, import S2, publish S2. Do not migrate S1 at all. S1, which is published in environment 1, is not migrated to environment 2.	If S2 depends on changes made as part of S1, then those changes will be missing in environment 2.	Publish both sandboxes. You will be able to re-publish them.
Migrating sandboxes from multiple source environments: In environment 1, create sandbox S1, make changes to S1, export and publish S1. In environment 2, create sandbox S2, makes changes to S2, export and publish S2. In environment 3, import S1, publish S1. Import S2, and publish S2.	If there is any overlap between S1 and S2, for example both sandboxes updated the same MDS document, then changes made as part of S1 will be lost. For example, if AD connector form is created as part of S1 and EBS connector form is created as part of S2, then there will be overlap in CatalogAM.xml.xml and BizEditor resource bundle file. After the migration, both CatalogAM.xml.xml and BizEditor resource bundle only contain changes for EBS Connector developed as part of S2.	Manually merge the sandboxes into one.

19.1.3 Creating a Sandbox

You can create a sandbox from Identity Self Service or Identity System Administration.

To create a sandbox:

Log in to Oracle Identity Self Service or Oracle Identity System Administration.
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.
On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.
In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.
In the Sandbox Description field, enter a description of the sandbox. This is an optional field.
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.
Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.

19.1.4 Activating a Sandbox

You must activate a sandbox to use it.

To activate a sandbox:

From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to activate.
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.

19.1.5 Deactivating a Sandbox

You can deactivate a sandbox to stop allowing changes to metadata objects, thereby disallowing UI customization.

To deactivate a sandbox:

From the table showing the available sandboxes in the Manage Sandboxes page, select the active sandbox that you want to deactivate.
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 deactivating the sandbox, then Oracle Identity Manager prompts that all the tabs will be closed before the sandbox can be deactivated.

19.1.6 Viewing and Modifying Sandbox Details

You can view and manage sandboxes from the Manage Sandboxes page of the UI.

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

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.
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.

19.1.7 Exporting a Sandbox

Export all changes stored in the sandbox including sandbox metadata to a ZIP file.

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

From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to export.
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.

19.1.8 Importing a Sandbox

Import the sandbox archive (ZIP file) to an environment.

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

On the toolbar, click Import Sandbox. The Import Sandbox dialog box is displayed.
In the Sandbox Archive field, enter a path to the sandbox archive that you exported.
Click Import.
Click Refresh. The sandbox, which is imported to the target deployment, is displayed in the Available Sandboxes tab.

19.1.9 Publishing a Sandbox

Publish a sandbox to merge the changes stored in the sandbox to the mainline and make it available to other users.

To publish a sandbox:

Note:

Make sure that you export the sandbox before publishing it. After the sandbox is published, it cannot be exported anymore, and therefore, there is no way to migrate it to another environment.
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.

From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to publish.
On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.
Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.
You can click the Published Sandboxes tab to view a list of the published sandboxes.

19.1.10 Publishing Sandboxes in Bulk and Sequence

Publish multiple sandboxes in bulk and in sequence by creating and using a CSV file with the names of sandboxes in the sequence in which you want to publish them.

To publish sandboxes in bulk and sequence:

Create a CSV file with the names of the sandboxes in the sequence in which you want to publish them, separated by commas. Save the file.
In the Manage Sandboxes page, click Bulk Publish.
The Bulk Import and Publish dialog box is displayed.
In the Sandbox Archive section, click Choose Files, navigate to the directory that contains the sandbox zip file, and select the file to include it in the list of sandboxes to be published. Repeat the selection for all the sandboxes that you want to publish.

Note:
Both file selections, sandbox archive and CSV file, are mandatory to proceed for bulk publish.
Click Choose Files adjacent to the Sandbox file to be uploaded field. Navigate and select the CSV file containing the sandbox names and sequence, which you saved in step 1.
Click Generate Sandbox Sequence. The sandbox names along with the sequence in which they will be published as specified in the CSV file are displayed in the Sandbox Sequence field.
In the Sandbox Sequence field, review the sandbox names to be published and the sequence in which they will be published.
If you want to change the sandbox archives or the sequence, then edit the CSV file with the correct sandbox names and sequence, select it in the Sandbox file to be uploaded field, and click Generate Sandbox Sequence again. Otherwise, click Publish.

19.1.11 Deleting a Sandbox

Delete a sandbox when you no longer need it.

To delete a sandbox:

From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you want to delete.
On the toolbar, click Delete Sandbox. A message is displayed asking for confirmation.
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.

19.1.12 Reverting Changes

Before publishing a sandbox, all customizations within a sandbox can be reverted to the default settings.

This section describes how to revert the changes made in a sandbox. It contains the following topics:

19.1.12.1 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 committed 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. Also, if you are unable to login to Oracle Identity System Administration after customizing the interface and publishing the sandbox, then perform the procedure described in Reverting Changes When Unable to Login to Identity System Administration.

19.1.12.2 Reverting Changes When Unable to Login to Identity System Administration

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

Login to Oracle Enterprise Manager.
In Application Deployments, select oracle.iam.ui.console.self-service.ear.
On the top-right of the page, select Application Deployment, and then select MDS Configuration from the list.
At the bottom of the screen, select Runtime MBean Browser under the Advanced Configuration section. The right side of the screen refreshes.
Click the Operations tab.
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.
Click Return to go back to the Operation tab.
Find the promoteMetadataLabel MBean operation.
Invoke the promoteMetadataLabel MBean operation, and enter the value that you copied in step 6.
Restart Oracle Identity Manager.
Login to Oracle Identity System Administration.

Note:

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

19.2 Skin Customization in Oracle Identity Governance

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

The following sections describe how to perform skin customization in Oracle Identity Manager:

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:

http://docs.oracle.com/cd/E15523_01/web.1111/b31973/af_skin.htm#ADFUI330

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

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

19.2.1 Configuring a New Skin

You can extend oim-alta skin to configure custom skins. The oim-alta skin is shipped with Oracle Identity Manager. The custom skin files and skin definition are deployed as part of the oracle.iam.ui.custom-dev-starter-pack.war shared library.

To create, deploy and configure a custom skin that extends oim-alta skin:

Create META-INF directory with trinidad-skins.xml file, as shown:

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

Create META-INF/skins/my-skin/my-skin.css, and add your custom skin selectors, as described in section "Customizing the Appearance Using Styles and Skins" in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Create a JAR file that contains the META-INF directory. For example, you can use the following command to create the JAR file:
```
jar cf skins.jar META-INF
```
You must run the command from the parent directory of the META-INF directory. If the skin is referencing custom images or other files, then include them in the JAR file as well.
Include the newly created JAR file in the WEB-INF/lib/ directory of the oracle.iam.ui.custom-dev-starter-pack.war shared library. You can find the deployed version of the oracle.iam.ui.custom-dev-starter-pack.war shared library in the IDM_HOME/server/apps/ directory. For example, you can use the following commands to update the existing oracle.iam.ui.custom-dev-starter-pack.war and include the additional JAR file:
```
mkdir -p WEB-INF/lib
cp skins.jar WEB-INF/lib
jar uf oracle.iam.ui.custom-dev-starter-pack.war WEB-INF/lib/skins.jar
```
Copy the updated oracle.iam.ui.custom-dev-starter-pack.war to the IDM_HOME/server/apps/ directory.
Login to Oracle Identity System Administration, and change the values of the following system properties:

Skin Family for OIM UI: Change the value to my-skin, or whatever value you specified for family in the trinidad-skins.xml file.

Skin Version for OIM UI: Change the value to v1, or whatever value you specified for version in the trinidad-skins.xml file.
Restart Oracle Identity Manager server.

19.2.2 Changing Branding and Logo

Customizing or changing UI artifacts, such as logo, buttons, and menu items, can be done at runtime.

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 (also referred to as the legacy Advanced Console), for example, the window that opens when you click Configuration Properties under System Configuration, then see:

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

To change the logo image:

Note:

To change the logo image the custom logo must be placed in the $OIM_HOME/server/apps/oim.ear/iam-consoles-faces.war/images/ folder, where OIM_HOME is the full path of the Oracle Identity Manager home.

Log in to Oracle Identity Self Service as the system administrator.
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.
Click Customize. The customization panel is displayed at the top of the page.
Click Structure. The component tree is displayed. The component tree shows all the ADF components of the page.
Click the logo. The Confirm Shared Component Edit dialog box is displayed asking for confirmation.
Click Edit. The logo object is selected in the component tree, as shown in Figure 19-1:

Figure 19-1 The Object Library in WebCenter Composer

Description of "Figure 19-1 The Object Library in WebCenter Composer"
Click the icon. The Component Properties dialog box is displayed.
In Component Properties, click the down arrow icon next to the Icon property, and select Expression Builder.
In the Expression Builder, replace the default value of #{attrs.logoImagePath} with your logo path, that is /../oim/images/$LOGO_NAME, where LOGO_NAME is the name of the custom logo.
Tip:
- Customizing the default EAR and WAR files, such as Self Service EAR, System Administration EAR, and xlWebApp.war, is not supported.
- 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.
- 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.
Click Apply. The logo has changed to the new one you specified.
To change the Identity Self Service global banner, click the Identity Self Service text, and open the Component Properties dialog box.
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. Perform the steps described in Customizing Unauthenticated Pages.
In the Display Options tab of the Component Properties dialog box, click the down arrow next to the Value field, and select Expression Builder. The Expression Editor dialog box is displayed.
With the Type a value or expression selected, enter a text to replace Identity Self Service, and click OK.
Click Apply.
Click Close to close WebCenter Composer.
Publish the sandbox.

19.3 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, organization, catalog, and provisioning target resource entities.

The following sections describe the customization:

19.3.1 Customizable Entity Artifacts

You can customize artifacts for various entities, such as user, role, organization, and catalog, and provisioning target resource forms.

Table 19-2 lists the artifacts that can be customized for each entity.

Table 19-2 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
Organization	Create page Modify Page Advanced Search interfact, 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 Administering Oracle Identity Governance for information about creating and managing forms by using the Form Designer

19.3.2 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://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html

This section contains the following topics:

19.3.2.1 Available EL Expressions in the User Context

The OIMContext bean is defined as an ADF session-scoped bean and provides access to information about the logged-in user.

Table 19-3 lists the available EL expressions in the Oracle Identity Manager user context.

Table 19-3 EL Expressions in User Context

EL	Description
#{oimcontext.currentUser['ATTRIBUTE_NAME']}	Access value of the ATTRIBUTE_NAME attribute of the logged-in user.
#{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.adminRoleMap['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.

19.3.2.2 Retrieving User Attribute Values From the OIMContext Bean

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']}

19.3.2.3 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 19-4 lists the EL expressions involving RequestFormContext.

Table 19-4 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, MODIFY, ENABLE, DISABLE, and REMOVE.
#{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.
#{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.
#{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.

19.3.2.4 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 and headers, or the values displayed on a certain page (for example, values displayed in the Status field of the Request Summary page), then perform the procedures described in the following topics:

19.3.2.4.1 Creating Custom Resource Bundles

To create custom resource bundles:

Open the oracle.iam.ui.custom-dev-starter-pack.war shared library. The deployed version of the library is in the IDM_HOME/server/apps/ directory.
Create a new CustomResourceBundle.properties file.
In the new file, enter the key value pairs, for example:
```
CUSTOMRB_BANNER_TEXT=My Identity and Access
```
Create all localized files, for example CustomResourceBundle_it.properties and CustomResourceBundle_es.properties, in the same directory.
Repackage the custom WAR, and update the custom WAR deployment in the server.

19.3.2.4.2 Using the Resource Bundles

To use the resource bundles:

In Oracle Identity Self Service, create a sandbox, and click Customize.
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}
```
Click Test to test the expression. Click OK, then click Apply.
Click OK to close the Component Properties dialog box.
Export the sandbox, and then publish the sandbox.

Note:

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

19.3.3 Showing or Hiding UI Components Conditionally

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.

19.3.4 Showing Request Profiles Conditionally

Use EL expression to conditionally display a catalog request profile.

To show a catalog request profile conditionally:

Login to Oracle Identity Self Service.
Activate a sandbox.
In the Self Service tab, click the Request Access box, and select Request for Self. The Add Access page of the Request Access wizard is displayed.
Click Customize. Click Structure. The component tree is displayed.
Using the component tree, navigate to the iterator component within Request Profiles. The iterator component has panelGroupLayout subcomponent, which represents single request profile.
Select panelGroupLayout:horizontal, which is a subcomponent of panelGroupLayout:vertical inside the iterator component, and click Edit in the Web Composer.
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.
Publish the sandbox to globalize the change.

19.3.5 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 19-5 lists the ADF validators.

Table 19-5 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.

19.3.6 Marking Input Attribute as Required

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 Conditionally.

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

19.3.7 Adding a Link or Button

Use the Add Content dialog box to add a link or button to a UI page.

To add a link to Oracle Identity Self Service:

From any page in Oracle Identity Self Service, open WebCenter Composer.
Select the top panel on which you want to include the link. The ADF component is selected in the component tree.
Click the plus (+) icon to open the Add Content dialog box. Navigate and select the Web Components component from the list of components.

The Web Components component in the Add Content dialog box is shown in Figure 19-2:

Figure 19-2 The Add Content Dialog Box

Description of "Figure 19-2 The Add Content Dialog Box"
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.

Note:

For a complete list of UI components, see Using Common ADF Faces Components in Developing Web User Interfaces with Oracle ADF Faces.
Click Close to quit customization mode.
Note:

For more details, see the following sections:
- Launching Taskflows
- Creating an External Link

19.3.8 Hiding and Deleting an ADF Component

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

This section describes how to hide and delete an ADF component. It contains the following topics:

19.3.8.1 Hiding an ADF Component

To hide an ADF component:

In Oracle Identity Self Service, go to the page on which you want to hide a component.
Click Customize to open WebCenter Composer.
Click Structure to open the component tree.
Click the component on the page that you want to hide. The corresponding ADF component in the component tree is selected.
Right-click the selected ADF component in the component tree, and select Hide.

19.3.8.2 Deleting an ADF Component

To delete an ADF component:

From the Oracle Identity Self Service page on which you want to delete any UI component, open Web Composer.
Click Structure to open the component tree.
Click the component on the page that you want to delete. The corresponding ADF component in the component tree is selected.
Right-click the selected ADF component in the component tree, and select Delete.
In the Delete Component Confirmation box, click Delete.

19.3.9 Showing and Hiding Attributes

Use the Child Components tab of the Component Properties dialog box to show or hide attributes in a page.

To show or hide attributes in a page:

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.
Click Customize to open Web Composer.
Click Structure to open the component tree.
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.
Click Edit. The ADF component for the selected region is selected in the component tree.
Open the Component Properties dialog box.
Click the Child Components tab. All the UI components of the selected region are displayed. Figure 19-3 shows a sample Child Components tab in the Component Properties dialog box.

Figure 19-3 The Child Components Tab

Description of "Figure 19-3 The Child Components Tab"
Select or deselect the checkbox corresponding to the attributes to show or hide the attributes respectively.

Note:

If you do not see an attribute listed here, then you must add the attribute into the form. See Adding a Custom Attribute in Administering Oracle Identity Governance for details.
Click Apply. The selected attributes are hidden or shown based on your selection.
Click OK, and then click Save on the toolbar.

19.3.10 Customizing Unauthenticated Pages

You can customize the unauthenticated pages of the Identity Self Service, such as User Registration page or Sign In page.

To customize the unauthenticated pages:

Login to Oracle Identity Self Service as the system administrator.
Create and activate a sandbox, and click Customize.
Click the Self Service tab to open the Self Service Home page.
Click Structure to open the component tree.
Select the panelGridLayout component, as shown in Figure 19-4.

Figure 19-4 The panelGridLayout Component

Description of "Figure 19-4 The panelGridLayout Component"
Select the last gridRow component. The component is shown as grayed out.
Right-click the last gridRow component, and select Show Component. The gridCell component is displayed.
Right-click the gridCell component and select Show Component.
Close the Structure tab. A new home page tile named Unauthenticated Pages is displayed.
Click Add Content to switch to design view.
Click the Unauthenticated Pages tile. A menu is displayed. Each menu item represents a link to one of the unauthenticated pages. For example, click New User Registration, and you will be redirected to User Registration page.
Click the Structure tab. On the component pane search for the links you want to hide and right-click over each link you want to hide by selecting hide component.
Do not close the customize page, instead type in the browser address bar the URL to the identity console. For example: http://<host:port>/identity.
Hide the Unauthenticated pages tile hiding the gridCell from Step 7 and gridRow from Step 6 in that order.
Publish the sandbox.

19.3.11 Customizing the Toolbar Contents

Use the Toolbar Components tab of the Component Properties dialog box to show or hide buttons on a toolbar.

To show or hide buttons in the toolbar:

Login to Oracle Identity Self Service as the system administrator.
Go to the page that has to be customize. Select the toolbar.
Create and activate a sandbox, and click Customize.
Click Structure to open the component tree.
Select the toolbar component as shown in Figure 19-5.

Figure 19-5 The toolbar, (x)group component

Description of "Figure 19-5 The toolbar, (x)group component"
To show the buttons in the toolbar:
1. Right-click the hidden component.
2. Select the Show Component option, and click Apply. The hidden button are enabled as shown in Figure 19-6.
  
  Figure 19-6 The ()group, toolbar component
  
  Description of "Figure 19-6 The ()group, toolbar component"
To hide the buttons in the toolbar:
1. Right-click the component you want to hide.
2. Select the Hide Component option, and click Apply. The button are disabled as shown in Figure 19-5.

19.3.12 Customizing Certification Pages

Customizing the pages in Identity Self Service related to the Certification feature involves customizing the certification details pane, adding custom attributes to the certification table, and customizing the certification table.

This section contains the following topics:

19.3.12.1 Customizing the Certification Detail Pane

The information from the row selected in the certification table can be used for customizing the detail pane found below the table. The procedure in this section can be used to customize the user certification detail pane. The same procedure can be followed for any certfication type.

After you have entered the customization mode, perform the following steps:

Edit the panelFormLayout containing the User Detail Information.
Click Add Content.
Select Data Component - Certification.
Select UserCertificationUserVO1.
Search for the attribute you want to add, for example Title, and click Add.
Select ADF Readonly Input Text with Label component.

The input component is added to the page, but a value for it is not displayed. A label is added that shows the name of the attribute.
Select the inputText component in the page source panel, and click Edit. The Component Properties dialog box is displayed.
Scroll down and find the Value attribute, and open the Expression Builder.
Edit the expression value and set it to the following:
```
#{pageFlowScope.p1_row_idcTitle}
```
Save the changes and close Web Composer. Select a row in the table.
When a row is selected from the table, the information is stored in the pageFlowScope. To display this information in the detail pane, steps 1 through 10 must be followed to extract the correct data. The format of the EL to follow is:
```
#{pageFlowScope.p1_row_ATTRIBUTE_NAME}
```
Page 1 table information can also be used in page 2 by using the same format. Because the data is stored in the pageFlowScope, the information remains in the scope making it available for display. Page 2 has a Page 1 Detail section at the top of the page showing a reference back to the item on page 1. You can add more page 1 details here using p1_row_ATTRIBUTE_NAME in the expression.

The steps documented in this section apply to page1 or the summmary page, of the current certification. If you want to customize page 2 or the detail page, then use the following format:
```
#{pageFlowScope.p2_row_ATTRIBUTE_NAME}
```

19.3.12.2 Adding Custom Attributes to the Certification Table

To create a UDF and add it to the certification table:

Create and activate a sandbox.
Create a new user UDF, as described in Creating a Custom Attribute in Administering Oracle Identity Governance.
Publish the sandbox.
To add the UDF, create and activate a new sandbox.
Navigate to the Certification Dashboard, and open the certification detail page for an entity.
Click Customize. Click Structure to open the component tree.
Click the table on the certification detail page. Click Edit on the Confirm Task Flow Edit message box.
With the table selected on the component tree, click the plus (+) icon to open the Add Content dialog box.
Click Data Component - Certification.

Select the VO corresponding to the table, for example, ApplicationCertificationEntitlementVO1.

The following table lists the VOs that are to be selected for various types of certifications:

Certification Page	VO
User Certification Phase 1 Page 1	UserCertificationUserVO
User Certification Phase 2 Page 2	UserCertificationPhase2EntitlementVO
Role Certification Detail Page	RoleCertificationMemberVO
Application Instance Certification Detail Page	ApplicationCertificationEntitlementVO
Entitlement Certification Detail Page	EntitlementCertificationEntitlementMemberVO

Scroll down to the UDF you created, and click Add. Then, select ADF Table Column.
Click Close. The UDF column is added to the certification table.

Note:

To add a default attribute to the certification table, from the View menu, select Columns, ATTRIBUTE_NAME. The default attribute column is added to the table. Similarly, you can hide the attribute from the certification table by selecting it from the View, Columns.

19.3.12.3 Customizing the Certification Table

To customize the certification table, for example, to increase the size of the table via customization:

Create and activate a sandbox.
Go to the certification detail page, and click Customize.
Click Structure to open the component tree.
Click anywhere on the certification table so that table:t1 tag is selected on the component tree. Right-click table:t1, and select Edit. Alternatively, you can click the show properties icon on the toolbar of the component tree.

The Component Properties dialog box is displayed.
Scroll down to the Fetch Size property. Click the down arrow of the Fetch Size property, and select Expression Builder.
In the Expression Builder, select the Type a value or expression option, and enter the value as 75. Click OK.
Click Apply, and then click OK to close the Component Properties dialog box.
Click Close. The table has been expanded to 75 rows.

19.4 Securing a Task Flow Region Using EL Expressions

For each new task flow, there is an entry in the jazn-data.xml file.

The following is an 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.

19.5 Customizing Oracle Identity Governance Help

Oracle Identity Governance lets you develop and use online Help systems in the Oracle Identity Self Service and Oracle Identity System Administration.

This section describes how to develop the online Help system. It contains the following topics:

19.5.1 Adding Custom Help Topics

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

This section describes how to create, configure, and view custom help topics. It contains the following topics:

19.5.1.1 Creating Custom 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 Understanding OHW Deployment in Developing Help Systems with Oracle Help.

19.5.1.2 Referencing the Custom Help Topics

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.

19.5.1.3 Adding a Custom Help Topic to Identity Self Service

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 Home page in the Oracle Identity Self Service:

In Oracle Identity Self Service, activate a sandbox from the Manage Sandboxes page.
Go to one of the Home pages for Self Service, Compliance, or Manage, and click Customize.
Click Structure to open the component tree.
Click the section of the Home page where you want to add the help topic. Click Edit in the Confirm Edit Task Flow popup.
Click the plus (+) icon to open the Add Content dialog box.
Scroll down and click Web Components.
In the row for Command Image Link, click Add. The selected component is added to the Home page.
Select the added component, and click Edit. Open the Component Properties dialog box.
Click the Display Options tab.
In the Text field, enter the text for the help topic that will be displayed in the page.
In the Image field, enter the path and file name for the help icon image.
In the Action Listener field, enter the URL with the HelpTopicID of the custom help topic.
Click Apply, and then click OK.
Save and close customization mode. The help topic is added to the Home page. Clicking the help topic displays the help topic in the custom help book JAR file.

19.5.1.4 Viewing the Custom Help Topics

To view the custom help topics:

Login to Oracle Identity Self Service.
On the navigation bar at the top, click the down-arrow with the logged-in user name, and click Help. The Oracle Help for the Web window is displayed.
From the Book list, select Custom Help Topics for Oracle Identity Manager.
Expand the contents to view the help topics.

19.5.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.

This section describe the inline help configuration and how to add inline help. It contains the following topics:

19.5.2.1 Inline Help Configuration

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. If the CustomHelpResourceBundle.properties file is not available in the WAR library, then you can create it.

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.
_INSTRUCTIONS: 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.

19.5.2.2 Adding Inline Help

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:

In the Oracle Identity Self Service, navigate to the My Information page, and expand the Basic User Information section.
Click Customize, and open the component tree.
Click the Telephone field.
Click Edit, and open the Component Properties dialog box.
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.
Click Apply, and then click OK.
Save and close customization mode. An information image with the interrogation sign (?) is displayed before the Telephone field. When you place the mouse pointer on the icon, the inline help text is displayed.

See Also:

Displaying Tips, Messages, and Help on the 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

19.6 Customizing the Home Page

The Home pages provide a snapshot of the various functions in the Oracle Identity Self Service. You can customize the Home page by adding, removing, and rearranging containers or tiles.

This section describes how to customize the Home page. It contains the following topics:

19.6.1 Adding a Tile to the Home Page

Add a tile to the Identity Self Service Home page by customizing the UI.

To add a tile to the Home page:

Create and activate a sandbox.
Navigate to the Home page to which you want to add a tile.

Home pages consist of Panel Grid Layout, in which the page is divided into one or more grid rows and each grid row can have up to four grid cells. Figure 19-7 shows how the Home page is divided into grid rows and grid cells.

Figure 19-7 Home Page Panel Grid Layout

Description of "Figure 19-7 Home Page Panel Grid Layout"
Click Customize to switch to the customization mode.
Click Structure to switch to structure view.
Identify a position on the Home page where you want to add the new tile.

Before you can add a new tile, a new Grid Cell and optionally a new Grid Row must be added.
To add a grid row:
1. Select the Panel Grid Layout component as shown in Figure 19-8.
  
  Figure 19-8 Panel Grid Layout Component
  
  Description of "Figure 19-8 Panel Grid Layout Component"
2. Click the Add icon.
3. In the resource catalog, go to Web Components, and click the Add link next to grid row component. A new grid row is added to the page as a first child of the panelGridLayout component.
4. After adding the grid row component, you can change the values of Height, Margin Top, and Margin Bottom properties to align it with the existing grid rows.
To add a grid cell:
1. Select the Panel Grid Layout component, as shown in Figure 19-8.
2. Using the Component tree on the right, select one of the child grid rows where you want to add a new grid cell.
3. Click the Add icon.
4. In the resource catalog, go to Web Components, and click the Add link next to the grid cell component. A new grid cell is added to the page as a first child of the selected grid row component.
5. After adding the grid cell component, you can change the values of the Align, Margin End, Margin Start, Width properties to align it with the existing grid cells.
After a new grid cell has been added, select it, and click the Add icon. In the resource catalog, go to Web Components, and click the Add link next to the Dashboard Box component. A new dashboard tile is added to the page.

Note:

If the new tile is not displayed in the page, then refresh the page.
You can select the tile (DashboardBox component must selected in the Component tree), click the Edit icon, and change the values of the Hover Image, Image, Instruction Text, and Title Text properties.
Note:

After you add the tile, perform the steps described in one of the following sections to launch a new page by clicking on the tile:
Do not publish your sandbox yet.

19.6.2 Launching a New Page From the Tile Icon

Edit the Home page jsff.xml file to launch a new page from the tile icon.

To launch a page by clicking on the tile icon:

Export the sandbox and unzip it.

Open the Home page jsff.xml file that you are working on by using a text editor. Oracle Identity Manager has the following default Home pages for Self Service, Manage, and Compliance:

oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-home.jsff.xml
oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-manage.jsff.xml
oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-compliance.jsff.xml

Locate the oim:DashboardBox element in the XML file. The element looks similar to the following:

<oim:DashboardBox xmlns:oim="/componentLib1" instructionText="My user details" titleText="My Details" image="/images/Dashboard/myAccess.png" hoverImage="/images/Dashboard/myAccess_s2.png" iconClickable="true" id="e8533237995"/>

Ensure that the value of iconClickable is set to true.
Add a new element attribute named iconClickAction, set the value of the attribute to:
```
#{backingBeanScope.dashboardNavigationBean.launchTaskFlow}
```
Add two new af:clientAttribute elements as child elements of oim:DashboardBox, as follows:
```
<oim:DashboardBox xmlns:oim="/componentLib1" instructionText="My user details" titleText="My Details" image="/images/Dashboard/myAccess.png" hoverImage="/images/Dashboard/myAccess_s2.png" iconClickable="true" id="e8533237995" iconClickAction="#{backingBeanScope.dashboardNavigationBean.launchTaskFlow}">
<af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="taskFlowId" value="/WEB-INF/oracle/iam/ui/manageusers/tfs/user-details-tf.xml#user-details-tf"/>
<af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="title" value="My Details"/>
 

<af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="userLogin" value="#{oimcontext.currentUser['User Login']}"/>
<af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name=" usr_key" value="#{oimcontext.currentUser['usr_key']}"/>
</oim:DashboardBox>
```
Make sure that oim:DashboardBox now has opening and closing tags, as shown in the example. Also, ensure that the component IDs are unique.

Set values of taskFlowId and title client attributes. taskFlowId specifies which task flow will be launched, and title specifies the title of the new tab.

You can add additional client attributes if you want to pass input parameters to the task flow, as shown in the example in this step.
Tip:

If all the required taskflow parameters are not available through EL expressions, then you can implement a custom actionListener, as described in Launching Taskflows. The new actionListener method will be accessible through an EL that must be set to iconClickAction property.

If you want to launch some of the following UIs that are obsolete in this release of Oracle Identity Manager, then use the following ELs to set the iconClickAction property:
- Attestation Dashboard: #{backingBeanScope.dashboardNavigationBean.navigateAttestationDashboard}
- Pending Attestations: #{backingBeanScope.dashboardNavigationBean.navigatePendingAttestations}
- Legacy Homepage: #{backingBeanScope.dashboardNavigationBean.navigateHome}
Save the jsff.xml file, and re-create the sandbox ZIP file with the same name and structure as the original ZIP file.
Import the sandbox to Oracle Identity Manager.
Verify the changes and functionality of the new Home page tile.
Export the sandbox and publish it to make the changes available to all users.

19.6.3 Launching a New Page From the Tile Menu

Edit the Home page jsff.xml file to launch a new page from the tile menu.

To launch a page by clicking on tile menu item:

Export and unzip the sandbox.

Open the Home page jsff.xml file that you are working on by using a text editor. Oracle Identity Manager has the following default Home pages for Self Service, Manage, and Compliance:

oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-home.jsff.xml
oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-manage.jsff.xml
oracle/iam/ui/homepage/home/pages/mdssys/cust/site/site/self-service-compliance.jsff.xml

Locate the oim:DashboardBox element in the XML file. The element looks similar to the following:

<oim:DashboardBox xmlns:oim="/componentLib1" instructionText="Attestations" titleText="Attestations" image="/images/Dashboard/myAccess.png" hoverImage="/images/Dashboard/myAccess_s2.png" iconClickable="true" id="e85332379959"/>

Ensure that iconClickable is set to false.
Add new popupMenu f:facet element as child element of oim:DashboardBox, as follows:
```
<oim:DashboardBox xmlns:oim="/componentLib1" instructionText="Attestations" titleText="Attestations" image="/images/Dashboard/myAccess.png" hoverImage="/images/Dashboard/myAccess_s2.png" iconClickable="false" id="e85332379959">
<f:facet xmlns:f="http://java.sun.com/jsf/core" name="popupMenu">
<af:menu xmlns:af="http://xmlns.oracle.com/adf/faces/rich" id="m8278911">
<af:commandMenuItem xmlns:af="http://xmlns.oracle.com/adf/faces/rich" text="Attestation Dashboard"
actionListener="#{backingBeanScope.dashboardNavigationBean.navigateAttestationDashboard}"
id="cmi2478915"/>
<af:commandMenuItem xmlns:af="http://xmlns.oracle.com/adf/faces/rich" text="Pending Attestations"
actionListener="#{backingBeanScope.dashboardNavigationBean.navigatePendingAttestations}"
id="cmi2478916"/>
</af:menu>
</f:facet>
</oim:DashboardBox>
```
The menu can have as many command items as you want. The command menu items can use one of the following:
- Generic actionListener (#{backingBeanScope.dashboardNavigationBean.launchTaskFlow}) in conjunction with clientAttributes, as shown in Launching a New Page From the Tile Icon.
- Custom actionListener, as described in Launching Taskflows.
- One of the following actionListeners to launch interfaces that are obsolete in this release of Oracle Identity Manger, such as:
  - Attestation Dashboard: #{backingBeanScope.dashboardNavigationBean.navigateAttestationDashboard}
  - Pending Attestations: #{backingBeanScope.dashboardNavigationBean.navigatePendingAttestations}
  - Legacy Homepage: #{backingBeanScope.dashboardNavigationBean.navigateHome}
Make sure the oim:DashboardBox now has opening and closing tags, as shown in the example in this step. Also, ensure that component IDs are unique.
Save the jsff.xml, and re-create the sandbox ZIP file with the same name and structure as the original ZIP file.
Import the sandbox to Oracle Identity Manager.
Verify the changes and functionality of the new Home page tile.
Publish the sandbox to make the changes available to all users.

19.6.4 Showing Tiles Conditionally

By default, all the home page tiles are displayed. However, sometimes you might want to hide some of the tiles from certain users. For example, you might want to hide the Provisioning Tasks tile for end users.

To do so, select the Grid Cell component that contains the Provisioning Tasks tile, and use the following EL for rendered property (shown as Show Component in Web Composer):

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

See Showing or Hiding UI Components Conditionally for details.

19.7 Developing Managed Beans and Task Flows

To implement advanced customization in Oracle Identity Manager, you can develop new task flows and managed beans by using JDeveloper IDE and then package them in the custom WAR file, which is oracle.iam.ui.custom-dev-starter-pack.war.

This section describes advanced customization using managed beans and task flows. It contains the following topics:

19.7.1 Types of Managed Beans

Managed beans can either be request beans or state beans.

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.

19.7.2 Prerequisites for Developing Managed Beans and Task Flows

Before developing a custom task details taskflow, you must have the following software installed:

Oracle Identity Governance 12c (12.2.1.3.0)
JDeveloper 12c (install by running the SOA quick start installer 12.2.1.3.0)

Note:

The same task details taskflow can be used for multiple human tasks as long as the human tasks have the same set of outcomes and share the same payload structure. Therefore, different taskflows must be built for approvals, challenge, provide information, and manual fulfillment tasks.

19.7.3 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:

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.
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.
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. Add ADF Model Runtime.
4. Click Add Library, 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.
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.

Note:

Some examples in the consecutive sections in this document use the FacesUtils class. For information about this class, see The FacesUtils Class.

19.7.4 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:

Click File, New.
Find and select ADF Model Project, and then click OK.
Provide the Project Name, for example CustomModel, and Project Directory, and then click Next.
Enter Default Package name as oracle.iam.ui.custom, and then click Finish. The new project is created.
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.
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.

Note:

Some examples in the consecutive sections in this document use the FacesUtils class. For information about this class, see The FacesUtils Class.

19.7.5 Adding Custom Managed Bean

Add your custom managed bean by creating a class and registering it with a taskflow.

To add your custom managed bean:

Right-click the ViewController project, and select New.
Select the Java Class category.
Provide the class name, for example CustomReqBean or CustomStateBean, and the package name.
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}
```

19.7.6 Deploying Custom Code to Oracle Identity Governance

Deploy the custom code by adding your custom JAR file to the dev-starter-pack.war file and updating the custom library in WebLogic Administration Console.

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

Copy the oracle.iam.ui.custom-dev-starter-pack.war to a temporary location.
Open the oracle.iam.ui.custom-dev-starter-pack.war.
Add the custom jar file to the WEB-INF/lib directory. If the lib directory does not exist, then create it.
Save the oracle.iam.ui.custom-dev-starter-pack.war file.
Copy the oracle.iam.ui.custom-dev-starter-pack.war file back to its original location in the $OIM_ORACLE_HOME/server/apps/ directory.
Stop Oracle Identity Manager Managed Server.
In WebLogic Administration Console, update the oracle.iam.ui.custom library deployment, and activate the changes.
Start Oracle Identity Manager Managed Server.

19.7.7 Using Managed Beans

You can develop managed beans to customize Oracle Identity Manager interface.

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.

19.7.7.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:

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;
    }

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);
        }
    }

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));    
    }

Package and deploy the managed bean, as described in Deploying Custom Code to Oracle Identity Governance.
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.
Note:

Ignore if the following error is displayed while setting EL expression for the rendered property:
```
"javax.faces.validator.ValidatorException:
java.lang.IllegalArgumentException: Control Binding 'usr_emp_type__c' not found"
```

19.7.7.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:

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;
    }

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 + "@example.com");    
}

Package and deploy the managed bean, as described in Deploying Custom Code to Oracle Identity Governance.
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.

19.7.7.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.

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;
    }

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);
        }
    }

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}", String.class));
    }

Package and deploy the managed bean, as described in Deploying Custom Code to Oracle Identity Governance.
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.
4. Set EL expression for the Show required property on the Manager field panelLabelAndMessage to point to the isInternUserTypeSelected() method defined is step 3.

19.7.7.4 Implementing Custom Field Validation

Custom field validation can be implemented using managed beans.

This section describes how to implement custom field validation using custom managed beans. It contains the following topics:

19.7.7.4.1 Custom Field Validation and Managed Beans

Managed beans can be used to introduce custom validations. 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.

19.7.7.4.2 Implementing Custom Field Validation Using Managed Beans

To implement custom validation using Managed Beans:

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;
}

Add method for validation in your managed bean 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));
    }

See Also:

The FacesUtils Class for more information about the FacesUtils class

Package and deploy the managed bean, as described in Deploying Custom Code to Oracle Identity Governance.
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. For example:
```
<mds:attribute name="binding" value="#{backingBeanScope.validatorBean.startDateID}"/>
      <mds:attribute name="validator" value="#{backingBeanScope.validatorBean.validator}"/>
```
  Note:
  
  The validator property cannot be added directly by using the Web Composer. This must be set manually in the MDS file for the JSFF, as described in Setting the Validator Property.

19.7.7.4.3 Setting the Validator Property

The validator property cannot be added directly by using the Web Composer. This must be set manually in the MDS file for the JSFF. To do so:

Export the sandbox after setting component bindings for the Start Date and End Date fields by using the Web Composer.
Extract the contents of the ZIP file and locate the XML file for the form on which Start Date and End fields are modified. For example, the XML file for the Create User form is oracle/iam/ui/runtime/form/view/pages/mdssys/cust/site/site/userCreateForm.jsff.xml.

In a text editor, open the XML file and set validator for StartDate and EndDate fields. For Example:

<mds:modify element="_xg_36">
       <mds:attribute name="binding" value="#{backingBeanScope.validatorBean.startDateID}"/>
      <mds:attribute name="validator" value="#{backingBeanScope.validatorBean.validator}"/>
   </mds:modify>
   <mds:modify element="_xg_13">
      <mds:attribute name="binding" value="#{backingBeanScope.validatorBean.endDateID}"/>
      <mds:attribute name="validator" value="#{backingBeanScope.validatorBean.validator}"/>
   </mds:modify>

Save the changes, repackage the ZIP file (the sandbox archive), and then import it back to your environment.

19.7.7.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:

Define component binding for the User Type field and any parent component of Job Code, for example, form root panel.
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 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
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.

19.7.7.6 Customizing Forms By Using RequestFormContext

You can customize forms by using the RequestFormContext bean.

This section describes the RequestFormContext bean and how to use it to customize forms. It contains the following topics:

19.7.7.6.1 The RequestFormContext Bean

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.

19.7.7.6.2 Using the RequestFormContext Bean

This section describes the following example usage of the RequestFormContext bean:

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:

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;
    }

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:

private static final String
ACCOUNT_LOGIN_ATTRIBUTE = "UD_EBS2722_LOGIN__c";
    private static final String ACCOUNT_ID_ATTRIBUTE = "UD_EBS2722_ACCOUNTID__c";
    private static final String FIRST_NAME_ATTRIBUTE = "firstName__c";
    private static final String LAST_NAME_ATTRIBUTE = "lastName__c";
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);
        }
    }

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;
    }

Package and deploy the managed bean. See Deploying Custom Code to Oracle Identity Governance for information about deploying the managed bean.
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.
  Note:
  
  The actionListener property cannot be set by using the Web Composer. This must be set manually as follows:
  1. Export the sandbox.
  2. Edit the JSFF to set the actionListener attribute value. For example:
```
<mds:attribute name="actionListener" value="#{backingBeanScope.accountFormReqBean.submitButtonActionListener}"/>)
```
  3. Import the updated sandbox.
  This procedure is applicable to setting the actionListener property in all the examples in this document.
4. Set the rendered property to point to the isPrepopulateButtonRendered() method implemented in step 3.

19.7.7.7 Overriding the Submit Button in Request Catalog

You 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:

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:

private static final String MORE_THAN_FIVE_TARGET_USERS_MSG = "Cannot submit request for more than five target users.";
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 });
        }    
    }

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

19.7.7.8 Launching Taskflows

You can create your custom UI taskflow and launch them.

This section describes how to launch taskflows and how to add your own UI or taskflows. It contains the following topics:

19.7.7.8.1 Launching a Taskflow in Self Service

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:

Develop a custom managed bean with the following method, which is also called action listener:

public void launchMyTaskFlow(ActionEvent evt){
       
User user = OIMClientFactory.getAuthenticatedSelfService().getProfileDetails(null);
       String taskFlowId = "/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-details-tf.xml#user-details-tf";
       // This id uniquely identifies the taskflow after launch. Add a suffix, for example entityPrimaryKey, to make it unique.
       String id = "user-detail-tf";  
       String name = user.getDisplayName() ;  // this is shown as the tab title
       String description = ""; // Add any suitable description
       String icon = "/images/user.png";
       String  helpTopicId = ConstantsDefinition.DEFAULT_HELP_TOPIC_ID; // Or your custom OHW integrated help topic id
       boolean inDialog = false;
       Map params = new HashMap();  // These are your taskflow's input parameters being passed from this launcher method
       params.put("userLogin",  user.getLogin());   
 
       String jsonPayLoad = TaskFlowUtils.createContextualEventPayLoad(id, taskFlowId, name, icon, description, helpTopicId, inDialog, params);
       TaskFlowUtils.raiseContextualEvent(TaskFlowUtils.RAISE_TASK_FLOW_LAUNCH_EVENT, jsonPayLoad);
 }

Note:

The above code snippet uses the user details public taskflow to display the user details when the user login is provided. For a list of available public taskflows that you can use for customization of UI, see Using Public Taskflows.

Package and deploy the managed bean, as described in Deploying Custom Code to Oracle Identity Governance.

Using sandbox and Web Composer customization, add an ADF CommandLink to the correct page (JSFF file). Open the sandbox zip, and edit the jsff.xml to bind actionListener for that link to the managed bean method.
Ensure that the page definition of the jsff has the raiseTaskFlowLaunchEvent binding. To find the name of the page definition file, you first need to know the name of the jsff page on which you have the launch link.
If your launch link is on a custom jsff page, for example, your page name is my-custom.jsff, then look for a file named my-custom_pageDef.xml within the same JDev project. JDev automatically creates this file for each jsff. You must add the following eventBinding into this pageDef xml file:
```
<eventBinding id="raiseTaskFlowLaunchEvent">
      <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
        <event name="oracle.idm.shell.event.TaskFlowLaunchEvent"/>
      </events>
    </eventBinding>
```
Note:

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

19.7.7.8.2 Adding Custom Taskflow

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:

Write a managed bean and register using adfc-config.xml in oracle.iam.ui.custom-dev-starter-pack.war.
Add a new commandLink or commandButton on the page where you want to display the link or button by using Web Composer.
Set the actionListener property of the link or button component that you added to point to the actionListener method.
Raise the contextual event using the managed bean, which will be handled by Oracle Identity Manager. The taskflow is launched.

19.7.7.9 Creating an External Link

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

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");
    }
```
Package and deploy the managed bean. See Deploying Custom Code to Oracle Identity Governance for information.
Add a new commandLink or commandButton to the page on which you want to display the link or button by using Web Composer. See Adding a Link or Button for details.
Set the actionListener property of the link or button component that you added to point to the actionListener method.

19.7.8 Using Managed Beans to Populate Request Attributes

Request attributes can be populated by using managed beans or by using the prepopulate plug-in.

This section describes the following approaches for populating request attributes:

19.7.8.1 Populating Request Attributes Using Managed Beans

Populating request attributes by using managed beans is done by creating a managed bean, deploying it to the placeholder library, and customizing the UI to add the button to the page.

This section contains the following topics:

19.7.8.1.1 Approach Taken to Populate Request Attributes Using Managed Beans

This approach involves creating a managed bean that gets invoked when the user clicks a custom button. The managed bean must be deployed to the Oracle Identity Manager customization placeholder library, which is oracle.iam.ui.custom-dev-starter-pack.war. The button, referred to as the Prepopulate button, is part of the UI customization and must be manually added to the page by using Web Composer.

The managed bean code is responsible for fetching the information to be populated in the request form. It uses Oracle Identity Manager APIs to get the beneficiary information from the request and from the user management layer, and uses JSF/ADF APIs to update the request form UI components.

19.7.8.1.2 Creating the Java Class

To populate request attributes by using managed beans, you must first create the Java class. To do so:

Create the JDev application workspace and project, as described inSetting Up the ViewController Project.

Create a Java class. In this example, the complete class name is com.oracle.demo.iam.prepop.view.PrePopulateMBean. This class contains:

Two member variables that hold references to the UI components, the custom Prepopulate button and its parent container.
Accessor methods (get and set) for the variables member variables.
An action listener type method to be invoked when the user clicks the custom Prepopulate button.
A method that returns a boolean value determines when the custom Prepopulate button must be disabled

The custom code for this example is:

public class PrePopulateMBean {
 
    private UIComponent rootPanel;
    private UIComponent prepopulateButton;
 
    public PrePopulateMBean() {
        super();
    }
 
    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;
    }
 
    public boolean isPrepopulateButtonRendered() {
        
        boolean ret = false;   
        RequestFormContext requestFormContext = RequestFormContext.getCurrentInstance();
        if (requestFormContext != null) {
            
            boolean isActionRequest   = (requestFormContext.getActionType() == RequestFormContext.ActionType.REQUEST);
            boolean singleUserRequest = false;
 
            if (requestFormContext.getBeneficiaryIds()!=null) {
                singleUserRequest = (requestFormContext.getBeneficiaryIds().size() == 1);
            }
            ret = isActionRequest && singleUserRequest;
        }    
        return (ret);            
    }
 
    public void actionListener(ActionEvent e) {
 
        if (e.getSource().equals(prepopulateButton)) {
            
            RequestFormContext requestFormContext = RequestFormContext.getCurrentInstance();
            List<String> beneficiaryIds = requestFormContext.getBeneficiaryIds();
            
            if (beneficiaryIds.size() == 1) {
                
                try {
                    User user = getUser(beneficiaryIds.get(0));
                    FacesUtils.setAttributeBindingValue("UD_OID_USR_FNAME__c", user.getFirstName());
                    FacesUtils.setAttributeBindingValue("UD_OID_USR_LNAME__c", user.getLastName());
 
                } catch (NoSuchUserException f) {
                    f.printStackTrace();
                } catch (UserLookupException f) {
                    f.printStackTrace();
                }
            }
        }
        FacesUtils.partialRender(rootPanel);
    }
 
    private User getUser(String userKey) throws NoSuchUserException, UserLookupException {
        
        UserManager userMgr = OIMClientFactory.getUserManager();
        
        HashSet<String> searchAttrs = new java.util.HashSet<String>();
        searchAttrs.add(AttributeName.USER_LOGIN.getId());
        searchAttrs.add(AttributeName.LASTNAME.getId());
        searchAttrs.add(AttributeName.FIRSTNAME.getId());
        
        return userMgr.getDetails(userKey,searchAttrs, false);
    }
}

In the code for the Java class:

The isPrepopulateButtonRendered method returns true if a RequestContext is available, and if there is only one request beneficiary. The check on the RequestContext availability is required to avoid issues at the time of customization. This method is invoked when the custom Prepopulate button is loaded, or its container is refreshed.
The actionListener method executes a user search in Oracle Identity Manager by invoking the getUser method, which uses the request beneficiary information. Then, it directly sets values on the UD_OID_USR_FNAME__c and UD_OID_USR_LNAME__c UI components with the information returned from the user search, and invokes a partial rendering on the rootPanel. This is the panel that holds the custom button and the request form. The partial rendering will display the values in the respective fields. It is important to mention here that this custom code contains a direct reference to the UI components, and that these direct references can be found by exporting the sandbox. This method is invoked when the custom Prepopulate button is loaded or its container refreshed.
The FacesUtil class is responsible for rendering the UI changes. See The FacesUtils Class for the code for this class.

19.7.8.1.3 Declaring the PrePopulateMBean Class

Declare the PrePopulateMBean class as a managed bean in the JDev project. This makes the MBean available in the UI so that it can be invoked by using EL expressions. To configure this, specify the following values in the Managed Beans section of the View Controller project:

Name: prepopMBean
Class: com.oracle.demo.iam.prepop.view.PrePopulateMBean
Scope: backingBean

19.7.8.1.4 Deploying the View Controller Project and Custom Code

To deploy the View Controller project and the custom code:

Deploy the View Controller project as an ADF library JAR file. This type of deployment can be created in JDeveloper through the deployment profiles option. The deployment generates a JAR file. Copy this file into oracle.iam.ui.custom-dev-starter-pack.war, which is Oracle Identity Manager placeholder library. This file is available along with the other Oracle Identity Manager application packages, such as EAR and WAR files, at the $OIM_ORACLE_HOME/server/apps/ directory. Create a backup of this file before modifying it.
Deploy the custom code. See Deploying Custom Code to Oracle Identity Governance for information.

19.7.8.1.5 Customizing the UI to Add the Button

To manually add the Prepopulate button by customizing the UI:

In Oracle Identity Self Service, create and activate a sandbox. In this example, the sandbox name is RequestPrePop.
Navigate to the access catalog.
Search for the specific application instance to be customized. In this example, the application instance is called Local OID. Add the application instance to the cart, and click Checkout.
Click Customize.
Select Structure to open the component tree.
In the Cart Items and Details sections of the page, click close to the Details label. Make sure that the showDetailHeader:Details component is selected.
Click Edit. In the dialog box that opens, edit the Binding property, and configure the following EL using the Expression Builder:
```
#{backingBeanScope.prepopMBean.rootPanel}
```
This expression bind will make the UI invoke the setRootPanel method in the custom managed bean. Click OK.
Make sure that the showDetailHeader:Details component is selected. Click Add Content.
Scroll down, and open the Web Components section.
Click Add on the right of the Command Toolbar Button component. A button is added on the Details section.
Click the button, and then click Edit.
Edit the Text property, and set PrePopulate as the label.
Edit the Binding property and configure the following EL using the Expression Builder:
```
#{backingBeanScope.prepopMBean.prepopulateButton}
```
This bind is for invoking the setPprepopulateButton method in the custom managed bean. Click OK.
Edit the Disabled property, and configure the following EL by using the Expression Builder:
```
#{!backingBeanScope.prepopMBean.prepopulateButtonRendered}
```
This is to invoke the isPrepopulateButtonRendered method in the managed bean. Click Ok.
Click the Style tab. Set the Width property to 100, and the Margin - Left property to 100. Click OK. This configuration will properly place the PrePopulate button in the UI.
Exit the customization mode by clicking Close.

19.7.8.1.6 Configuring the Properties of the Prepopulate Button

To manually configure the properties of the Prepopulate button:

Navigate to the Sandbox page. De-activate and export the sandbox.
Save the sandbox ZIP file in the local file system.
Extract the ZIP file. In a text editor, open the XML file corresponding to the customization. In this example, the file is oracle/iam/ui/runtime/form/view/pages/mdssys/cust/site/site/OIDUserFormCreateForm.jsff.xml.

Search for the section defining the custom Prepopulate button, which can be similar to the following:

<af:commandToolbarButton xmlns:af="http://xmlns.oracle.com/adf/faces/rich" id="e8829502064" binding="#{backingBeanScope.prepopMBean.prepopulateButton}" text="PrePopulate"

Add the actionListener property to the custom Prepopulate button, as shown:
```
actionListener="#{backingBeanScope.prepopMBean.actionListener}
```
Save the file and repackage the ZIP. Make sure that the path is preserved when repacking the contens.
Import the sandbox, and import the ZIP file. Make sure that the sandbox is not active when importing it.
Activate the sandbox.

19.7.8.1.7 Testing the Customization

To test the UI customization:

Navigate to the Catalog, find the application instance and add it do the shopping cart.
In the cart summary page, the custom Prepopulate button is displayed.when clicking on it, the First Name and Last Name fields will be updated with the beneficiary's information
Click the Prepopulate button. The First Name and Last Name fields are updated with the beneficiary's information.
Publish the sandbox.

19.7.8.2 Populating Request Attributes by Using the Prepopulate Plug-in

Prepopulate plug-ins can be used when the same logic is to be executed for both UI and API request creation, and can also be used when a UI interaction is not required. In this approach, a plug-in is present for each attribute that must be prepopulated in the request. The same plug-in can be used across different resources and different attributes.

The plug-in code implements the oracle.iam.request.plugins.PrePopulationAdapter interface. The following is an example code:

package com.oracle.demo.iam.prepop.plugin;
 
import java.io.Serializable;
 
import java.util.HashSet;
import java.util.List;
 
import oracle.iam.identity.usermgmt.api.UserManager;
import oracle.iam.identity.usermgmt.api.UserManagerConstants.AttributeName;
import oracle.iam.identity.usermgmt.vo.User;
import oracle.iam.platform.Platform;
import oracle.iam.request.vo.Beneficiary;
import oracle.iam.request.vo.RequestData;
 
public class UserLoginPrePop implements oracle.iam.request.plugins.PrePopulationAdapter {
 
    public UserLoginPrePop() {
        super();
    }
 
    public Serializable prepopulate(RequestData requestData) {
 
        String prePopUserId = null;
 
        List<Beneficiary> benList = requestData.getBeneficiaries();
        
        if(benList.size()==1){
            
            UserManager  usersvc = Platform.getService(UserManager.class);
            
            for(Beneficiary benf: benList){
                                        
                HashSet<String> searchAttrs = new java.util.HashSet<String>();
                searchAttrs.add(AttributeName.USER_LOGIN.getId());
            
                try {
                    User userBenef = usersvc.getDetails(benf.getBeneficiaryKey(),searchAttrs, false);
                    if (userBenef!= null) {
                        prePopUserId = userBenef.getLogin();        
                    }
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }
        return prePopUserId;
    }
}

A prepopulate plug-in is similar to any other plug-in in Oracle Identity Manager. The plug-in class is compiled and deployed to a JAR file. The JAR file must be added to a ZIP file in the lib directory. The ZIP file must contain in the root path a XML file declaring the plug-in. The XML used in this example is as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <plugins pluginpoint="oracle.iam.request.plugins.PrePopulationAdapter">
 <plugin pluginclass= "com.oracle.demo.iam.prepop.plugin.UserLoginPrePop" version="1.0" name="UserLoginPrePop">
  <metadata name="PrePopulationAdapater">
   <value>OracleDBUMForm::Username|OIDUserForm::User ID</value>
  </metadata>
 </plugin>
</plugins>
</oimplugins>

In the XML code:

The xmlns tag attribute must be present in the XML. Otherwise, the plug-in is not invoked by Oracle Identity Manager.
The value in the pluginpoint element must be oracle.iam.request.plugins.PrePopulationAdapter.
The metadata tag contains a value child node. This value child node must contain the pairs of FormName::AttributeName. Each pair indicates a form attribute that will be populated by the prepopulate plug-in. In this example, such attributes are Username in the OracleDBUMForm form and User ID in the OIDUserForm form. The form names are configured when the ApplicationInstances and their forms were created, and not the process form created when the connector is imported into Oracle Identity Manager.

The prepopulate plug-in can be deployed to the $OIM_HOME/server/plugins/ directory, or it can be registered using the plug-in registration script. In production environments, it is always recommended to deploy the plug-in by using the command line so that the plug-in Zip file is uploaded to the database.

19.7.9 Using Public Taskflows

Oracle Identity Manager provides default taskflows for using them in the customized pages of Oracle Identity Self Service and to invoke other taskflows.

This section describes the public taskflows in Oracle Identity Manager. It contains the following topics:

19.7.9.1 About Public Taskflows

Oracle Identity Manager provides default taskflows for using them in the customized pages of Oracle Identity Self Service and to invoke other taskflows. For example, you can customize the user details page so that the user details of the manager will be displayed if you click the manager login name in the user details page.

The default or predefined taskflows are called public taskflows. While launching the public taskflows, you must provide appropriate values for some parameters. For example, to launch the request details page for a particular request, you must provide the request ID for the request.

19.7.9.2 Public Taskflows and Input Parameters

Table 19-6 lists the public taskflows provided by Oracle Identity Manager along with the input parameters that are required to invoke the taskflows.

Table 19-6 Public Taskflows

Taskflow name	Taskflow path	Description	Parameter	Mandatory
Request Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-details-tf.xml#request-details-tf	This is launched to view the details of a request that is submitted for approval.	requestID: The ID of the request whose details is to be displayed.	Yes
User Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-details-tf.xml#user-details-tf	This is launched to view the details of a user.	userLogin: User Login attribute value of the user whose details is to be displayed.	Yes
Role Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/role-details-tf.xml#role-details-tf	This is launched to view the details of a role.	roleName: Name of the role whose details is to be displayed.	Yes
Request Role	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-role-tf.xml#request-role-tf	This is launched to request for assignment of role(s) for beneficiaries.	roleNames: Names of the role(s) that are to be assinged. The names must be separated by commas.	Yes
Request Role	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-role-tf.xml#request-role-tf	This is launched to request for assignment of role(s) for beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficaries for whom the roles are to be assigned. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Revoke Role	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/revoke-role-tf.xml#revoke-role-tf	This is launched to request for revoking of role(s) that are assigned to beneficiaries.	roleNames: Names of the role(s) that are to be revoked.	Yes
Revoke Role	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/revoke-role-tf.xml#revoke-role-tf	This is launched to request for revoking of role(s) that are assigned to beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries for whom the roles are to be revoked. The values must be separated by commas. If a value is not provided, then the revoke action is applicable for the currently logged-in user.	No
Request Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-account-tf.xml#request-account-tf	This is launched to request for creation of account(s) for the beneficiaries.	appInstNames: Names of the application instance(s) where accounts are to be created. The values must be separated by commas.	Yes
Request Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-account-tf.xml#request-account-tf	This is launched to request for creation of account(s) for the beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries for whom the accounts are to be assigned. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Modify Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/modify-account-tf.xml#modify-account-tf	This is launched to modify the account details created for a user or beneficiary.	accountNames: Name of the accounts whose details are to be modified. The values must be separated by commas.	Yes
Modify Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/modify-account-tf.xml#modify-account-tf	This is launched to modify the account details created for a user or beneficiary.	userLogins: User Login attribute values of the users or beneficiaries whose account details are to be modified. The values must be separated by commas. If a value is not provided, then the revoke action is applicable for the currently logged-in user.	No
Enable Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/enable-account-tf.xml#enable-account-tf	This is launched to enable accounts assigned to user(s) or beneficiaries.	accountNames: Names of the accounts that are to be enabled. The values must be separated by commas.	Yes
Enable Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/enable-account-tf.xml#enable-account-tf	This is launched to enable accounts assigned to user(s) or beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries whose accounts are to be enabled. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Disable Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/disable-account-tf.xml#disable-account-tf	This is launched to disable accounts assigned to user(s) or beneficiaries.	accountNames: Names of the accounts that are to be disabled. The values must be separated by commas.	Yes
Disable Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/disable-account-tf.xml#disable-account-tf	This is launched to disable accounts assigned to user(s) or beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries whose accounts are to be disabled. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Delete Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/delete-account-tf.xml#delete-account-tf	This is launched to delete accounts assigned to user(s) or beneficiaries.	accountNames: Names of the accounts that are to be deleted. The values must be separated by commas.	Yes
Delete Account	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/delete-account-tf.xml#delete-account-tf	This is launched to delete accounts assigned to user(s) or beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries whose accounts are to be deleted. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Request Entitlement	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-entitlement-tf.xml#request-entitlement-tf	This is launched to request for the assignment of entilement(s) for beneficiaries.	entlmntNames: Names of the entilement(s) that are to be assigned. The values must be separated by commas.	Yes
Request Entitlement	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/request-entitlement-tf.xml#request-entitlement-tf	This is launched to request for the assignment of entilement(s) for beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries to whom the entitlements are to be assigned. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Revoke Entitlement	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/revoke-entitlement-tf.xml#revoke-entitlement-tf	This is launched to request for revoking of entilement(s) assigned to beneficiaries.	entlmntNames: Names of the entilement(s) that are to be revoked. The values must be separated by commas.	Yes
Revoke Entitlement	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/revoke-entitlement-tf.xml#revoke-entitlement-tf	This is launched to request for revoking of entilement(s) assigned to beneficiaries.	userLogins: User Login attribute values of the user(s) or beneficiaries from whom the entitlements are to be revoked. The values must be separated by commas. If a value is not provided, then the request action is applicable for the currently logged-in user.	No
Create User	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/create-user-tf.xml#create-user-tf	This is launched to create an user entity.	No parameters are required.	No
Modify User	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/modify-user-tf.xml#modify-user-tf	This is launched to modify the user details.	userLogins: User Login attribute values of the user(s) whose details are to be modified. If more than one userLogin attribute is provided as parameter, then bulk modify page is displayed. The values must be separated by commas.	Yes
Enable User	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/enable-user-tf.xml#enable-user-tf	This is launched to enable the disabled user(s).	userLogins: The User Login attribute values of the users that are to be enabled. The values must be separated by commas.	Yes
Disable User	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/disable-user-tf.xml#disable-user-tf	This is launched to disable the enabled user(s).	userLogins: The User Login attribute values of the users that are to be disabled. The values must be separated by commas.	Yes
Delete User	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/modify-user-tf.xml#modify-user-tf	This is launched to delete user(s).	userLogins: The User Login attribute values of the users that are to be deleted. The values must be separated by commas.	Yes
Catalog Search	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/catalog-search-tf.xml#catalog-search-tf	This is launched to specify the catalog search criteria and display the search results page or cart details page directly without using the catalog search page.	searchCrtieria: Various string attributes in the following format: {criteriaName: "string", allowSearch: "true/false", profileName: "string", directCheckout: "true/false", showEntityTypeSelector: "true/false", hiddenTag: "string", allowedEntityTypes: "string", tags: "string", entityType: "string", auditObjective: "string", riskLevel: "string", ANY_UDF: "string"} Here: criteriaName: Optional string attribute that will be displayed in the catalog results page. allowSearch: Optional boolean attribute to control rendering of tag search field in results page. profileName: Optional string attribute to take user to cart page by simulating the saved profile click. directCheckout: Optional parameter to add search results to the cart and take user to checkout page (true/false). showEntityTypeSelectorOptional boolean attribute to show entityTypeSelector dropdown. This is displayed only if allowSearch is also set to true. hiddenTag: Optional string attribute to further narrow down the search within the specified tags. allowedEntityTypes: Optional string attribute to show entityTypes in the entityTypeSelector dropdown. If more than one entity is to be shown, then they must be separated by the tilde (~) delimiter, for example, Role~Entitlement tags: Search criteria for tags. It is a mandatory string attribute except when profileName is specified. entityType: Optional string attribute specifying search criteria for entity type, such as role, entitlement, or application instance auditObjective: Default value of the audit objective attribute. riskLevel: Default values of the risk level attribute. Values can be 3(Low Risk), 5(Medium Risk), 7(High Risk). Any user-defined field (UDF) that you add in the request catalog.	Yes
Catalog Search	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/catalog-search-tf.xml#catalog-search-tf	This is launched to specify the catalog search criteria and display the search results page or cart details page directly without using the catalog search page.	userLogins: The User Login attribute values of the users to be displayed in the beneficiary table in the catalog search results page. The values must be separated by commas. If value is not passed, then the current logged-in user is shown in the beneficiary table.
Catalog Item Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/catalog-item-details-tf.xml#catalog-item-details-tf	This is launched to display the details of a catalog item.	catalogItemName: Name of the catalog item whose details are to be displayed.	Yes
Catalog Item Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/catalog-item-details-tf.xml#catalog-item-details-tf	This is launched to display the details of a catalog item.	catalogItemType: Type of the catalog item whose details are to be displayed. The valid values are Role, ApplicationIstance, or Entitlement.	Yes
User Roles	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-roles-tf.xml#user-roles-tf	This is launched to view the roles page of a given user.	userLogin: User Login attribute value of the user whose roles page is to be displayed.	Yes
User Accounts	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-accounts-tf.xml#user-accounts-tf	This is launched to view the accounts page of a given user.	userLogin: User Login attribute value of the user whose accounts page is to be displayed.	Yes
User Entitlements	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-entitlements-tf.xml#user-entitlements-tf	This is launched to view the entitlements page of a given user.	userLogin: User Login attribute value of the user whose entitlements page is to be displayed.	Yes
User Assigned Admin Roles	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/user-assigned-adminroles-tf.xml#user-assigned-adminroles-tf	This is launched to view the assigned admin roles page of a given user.	userLogin: User Login attribute value of the user whose assigned admin roles page is to be displayed.	Yes
Organization Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/org-details-tf.xml#org-details-tf	This is launched to view the organization details page.	orgName: Name of the organization whose details page is to be displayed.	Yes
My Access	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/my-access-tf.xml#my-access-tf	This is launched to display the access page of the currently logged-in user.	No parameters are required.	No
Change User Account Password	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/account-passwd-reset-tf.xml#account-passwd-reset-tf	This is launched to display the change user account password page for a given user.	accountName: Name of the user's account whose password is to be changed.	Yes
Change User Account Password	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/account-passwd-reset-tf.xml#account-passwd-reset-tf	This is launched to display the change user account password page for a given user.	userLogin: User Login attribute value of the user whose account password is to be changed.	Yes
Account Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/account-details-tf.xml#account-details-tf	This is launched to display the details of a user's account.	accountName: Name of the user's account whose details is to be displayed.	Yes
Account Details	/WEB-INF/oracle/iam/ui/taskflows/public/tfs/account-details-tf.xml#account-details-tf	This is launched to display the details of a user's account.	userLogin: User Login attribute value of the user whose account is to be displayed.	Yes

Note:

The parameters of all the public taskflows listed in Table 19-6 are of type java.lang.String.
The public taskflows can be launched by using contextual event as described in Launching Taskflows. Otherwise, public taskflows can be embedded in an ADF faces page. To embed public taskflows in an ADF faces page, the following parameter (in addition to the parameters listed in Table 19-6) must be added to the taskflow definition in the page definition file of the ADF faces page:

Parameter name: "uiShell"

value: "#{pageFlowScope.uiShell}"

19.7.10 Customizing Catalog Search

For advanced customizations to the catalog search, such as adding search fields and search operators, it is recommended to create a custom taskflow and then replace the default catalog taskflow with the custom taskflow.

For customizing the default catalog search form, see Configuring the Access Request Catalog in Administering Oracle Identity Governance.

This section describes how to implement a custom taskflow for catalog search. It contains the following topics:

19.7.10.1 Developing the Custom Taskflow

Develop the custom taskflow as a bounded taskflow based on page fragments in the ViewController project. Make sure that OIM client, OIM model, and OIM view libraries are also added to the ViewController project. For information about setting up the ViewController project, see Setting Up the ViewController Project.

The custom taskflow can be based on the taskflow template /WEB-INF/oracle/iam/ui/catalog/tfs/catalog-search-template.xml, as shown in Figure 19-9:

Figure 19-9 Catalog Taskflow Based on Template

Description of "Figure 19-9 Catalog Taskflow Based on Template"

By extending this template, values to the following parameters are automatically passed to the custom taskflow. These parameters can be accessed from pageFlowScope in the custom taskflow.

entityType: When requesting for roles, entitlements, or accounts from the My Access page of Identity Self Service, the value passed to this parameter is Role, Entitlement, Application Instance respectively.
showEntityTypeSelector: When requesting for roles, entitlements, or accounts from the My Access page, the value for this parameter is passed as false. This parameter can be used to hide the entity type selector in the custom taskflow.
showAppSelector: When requesting for entitlements from the My Accounts tab in the My Access page, the value for this parameter is passed as false. This parameter can be used to hide the application selector in the custom taskflow.
parentEntityKey: When requesting for entitlement from the My Accounts tab in the My Access page, the application instance key corresponding to the selected account is passed to this parameter.

The page fragment in the custom taskflow can be based on the template /oracle/iam/ui/catalog/pages/catalog-advanced-search-template.jspx, as shown in Figure 19-10:

Figure 19-10 JSF Page Fragment Based on Page Template

Description of "Figure 19-10 JSF Page Fragment Based on Page Template"

Make sure that the pageTemplateBinding is automatically added in the page definition of the custom page by Jdeveloper, as shown in Figure 19-11:

Figure 19-11 Page Bindings for JSF Page Fragments

Description of "Figure 19-11 Page Bindings for JSF Page Fragments"

19.7.10.2 Adding the Presentation Logic for the Custom Form

Add the presentation logic for the custom form in the search facet, as shown:

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:c="http://java.sun.com/jsp/jstl/core">
  <af:pageTemplate viewId="/oracle/iam/ui/catalog/pages/catalog-advanced-search-template.jspx"
                   value="#{bindings.pageTemplateBinding}" id="pt1">
    <f:facet name="search">
      <!-- ######## CUSTOM SEARCH CONTENT BEGIN ###### -->       
      <!-- ####### CUSTOM SEARCH CONTENT END########## -->      
    </f:facet>
  </af:pageTemplate>
</jsp:root>

19.7.10.3 Constructing the SearchCriteria Object

The search button on the custom form must have an action listener defined. In the action listener, construct the SearchCriteria object and invoke the following utility method:

oracle.iam.ui.catalog.view.CatalogAdvancedSearch.executeCatalogSearch(oracle.iam.platform.entitymgr.vo.SearchCriteria criteria)
public void searchActionListener(ActionEvent event){
    SearchCriteria criteria = null;
    //build your search criteria
    //and then call executeCatalogSearch
    CatalogAdvancedSearch.executeCatalogSearch(criteria);
}

19.7.10.4 Deploying the Taskflow

To deploy the custom taskflow:

Deploy the taskflow as part of the oracle.iam.ui.custom shared library. For information about deploying the bounded taskflow, see Deploying Custom Code to Oracle Identity Governance.

Add permissions to the custom taskflow by using the Authorization Policy Manager (APM) UI to secure the taskflow.

Note:

If WLST script is used to grant permissions to the custom taskflow, then use appStripe =”OIM”, as shown in the following example:

grantPermission(appStripe="OIM",
principalClass="oracle.security.jps.service.policystore.ApplicationRole",
principalName="OIMSysAdmin",
permClass="oracle.adf.controller.security.TaskFlowPermission",
permTarget="/WEB-INF/oracle/iam/ui/sample/catalogsearch/tfs/catalog-custom-search-tf.xml#catalog-custom-search-tf", permActions="view")

Update the Catalog Advanced Search Taskflow system property to point to the custom taskflow. Specify the value in the format TASKFLOW_DOCUMENT#TASKFLOW_ID. See Default System Properties in Oracle Identity Manager in Administering Oracle Identity Governance for information about this system property.
Restart Oracle Identity Manager server.

19.7.11 Customizing Task Details Page for Approval Tasks

Customizing the task details page for approval tasks involves building and creating a custom taskflow, creating a task details page, populating the page with task information, and configuring the human task to use the custom taskflow.

This section contains the following topics:

19.7.11.1 Prerequisites for Developing Custom Task Details Taskflow

Before developing a custom task details taskflow, you must have the following software installed:

Oracle Identity Manager 12c Release 2 (12.2.1.2)
Oracle SOA Suite 11g (11.1.1.9.0)
JDeveloper 11g (11.1.1.9.0) with Oracle SOA Composite Editor extension

Note:

The same task details taskflow can be used for multiple human tasks as long as the human tasks have same set of outcomes and share the same payload structure. Therefore, different taskflows must be built for approvals, challenge, provide information, and manual fulfillment tasks.

19.7.11.2 Building a Custom Taskflow for a Human Task

To build a custom taskflow for a human task:

Create a ViewController project. For information about setting up the ViewController project, see Setting Up the ViewController Project.
Create the task details taskflow, as described in Creating the Task Details Taskflow.
Go to Application Sources under the ViewController project, and then delete hwtaskflow.xml.
Create the task details page, as described in Creating the Task Details Page.
Populate the page with task information, as described in Populating the Page With Task Information.
In the application navigator, enable the Show Libraries option, as shown in Figure 19-12. This allows you to drag and drop taskflows from OIM view shared library to your custom task details taskflow.

Figure 19-12 Enabling Show Libraries

Description of "Figure 19-12 Enabling Show Libraries"
Add request information to the Details page. The taskflows from OIM View Shared library that can be dropped as a region on the Details page to show request-related information is described in Taskflows to Show Request-Related Information.
Add a separate page for email notification (optional). By default, for sending email notification, if there is no separate page for email, then the same task details page developed in this section is sent in email notification. Sometimes, limited information needs to be sent in email notification. In such scenarios, separate page for email notification can be developed. The email page will also be part of the same task details taskflow. For more information on building custom page for email, refer to Creating an Email Notification in the Developer's Guide for Oracle SOA Suite.
Deploy the taskflow as part of the oracle.iam.ui.custom shared library. For information about deploying the bounded taskflow, see Deploying Custom Code to Oracle Identity Governance.
Configure the human task to use the custom taskflow, as described in Configuring the Human Task to Use the Custom Taskflow.
Repeat step 10 for all the human tasks for which you want to reuse this custom taskflow.
Restart all servers.

19.7.11.3 Creating the Task Details Taskflow

To create the task details taskflow:

Navigate to the following directory in the shiphome:

IAM_HOME/server/workflows/composites/
Unzip the composite:
- For building details page for approvals and challenge tasks, unzip DefaultRequestApproval.zip.
- For building details page for provide information tasks, unzip ProvideInformation.zip.
- For building details page for manual fulfillment tasks, unzip DisconnectedProvisioning.zip.
Go back to JDeveloper, right-click the ViewController project created in Step 1, and select New.
Select Web Tier, JSF, and ADF task flow based on the human task.
In the file browser, navigate to the directory in which you unzipped the composite ZIP file. Select the appropriate human task file, as follows:
- For building details page for approvals task, select DefaultRequestApproval /ApprovalTask.task.
- For building details page for challenge task, select DefaultRequestApproval/ChallengeTask.task.
- For building details page for provide information task, select ProvideInformation/ApprovalTask.task.
- For building details page for manual fulfillment task, select DisconnectedProvisioning /ManualProvisioningTask.task.
In the Create Task flow dialog box, specify values for the following:

File Name: For example, request-approval-details-tf.xml.

Directory: Make sure that the taskflow is created under the WEB-INF/oracle/iam/ui/custom/ directory. All taskflows under the WEB-INF/oracle/iam/ui/custom/ directory are secured with view permission.

Task Flow ID: For example, request-approval-details-tf.
Click OK.

19.7.11.4 Creating the Task Details Page

To create the task details page:

Open the taskflow created in Step 2. Switch to diagram mode.
Rename taskdetails1_jspx view activity, for example, request-approval-details.
Right-click the view activity, and select Create Page. Provide values for the following:

File name: For example, request-approval-details.jspx

Directory: Put the JSPX file under the public_html/oracle/iam/ui/custom/ directory

Initial Page layout and content: Blank Page
Click OK.

19.7.11.5 Populating the Page With Task Information

To populate the page with task information:

In the Data Controls palette, the data control with your project name is already created. Use this data control to render task-related information on the details page.
To drop the Task object on the page, from the Create context menu, select Human Task, Complete Task without Payload, as shown in Figure 19-13.

Figure 19-13 Complete Task Without Payload

Description of "Figure 19-13 Complete Task Without Payload"
In the Edit Action dialog box, do not modify anything, and click OK.

Note that task-related content, such as actions, basic information, history, comments, and attachments are added to the page.

Note:

For manual fulfillment task, you can also choose the Complete Task with Payload option to show payload data. For approval, challenge, or provide information tasks, you can reuse Oracle Identity Manager taskflows mentioned in step 7 for showing payload-related information.

19.7.11.6 Taskflows to Show Request-Related Information

The following taskflows from OIM View Shared library can be dropped as a region on the Details page to show request-related information.

WEB-INF/oracle/iam/ui/catalog/tfs/request-summary-information-tf.xml: This taskflow shows basic request information. This is not applicable for manual fulfillment task.
WEB-INF/oracle/iam/ui/catalog/tfs/request-summary-details-tf.xml: This taskflow shows target users, related requests, and dependent requests. This is not applicable for manual fulfillment task.
WEB-INF/oracle/iam/ui/catalog/tfs/catalog-tf.xml: This taskflow shows cart items and form data for each item in the request. It should be used for all request types except create, modify, or delete role. This taskflow can be used for approvals, challenge, provide information, and manual fulfillment tasks.
WEB-INF/oracle/iam/ui/role/tfs/create-role-train-tf.xml: This taskflow should be used instead of catalog-tf taskflow for create, modify, or delete role types of requests. It is not applicable for challenge, provide information, and manual fulfillment tasks.

19.7.11.7 Configuring the Human Task to Use the Custom Taskflow

To configure the human task to use the custom taskflow:

Login to Oracle Enterprise Manager as WebLogic user.
Navigate to Farm_IAM_DOMAIN, SOA, soa_infra (SOA_SERVER), default, COMPOSITE_NAME. An example of composite name can be DefaultRequestApproval[5.0].
Click Component Metrics, HUMAN_TASK. Human task can be ApprovalTask or ChallengeTask or ManualProvisioningTask, as shown in Figure 19-14.

Figure 19-14 Human Tasks

Description of "Figure 19-14 Human Tasks"
Click the Administration tab.
Modify the URI in the existing entry to point to the custom taskflow, as follows:

Application Name: Worklist

Host Name: Hostname in OIMExternalFrontendURL

HTTP Port: HTTP Port in OIMExternalFrontEndURL if SSL is not configured

HTTPS Port: HTTPS Port in OIMExternalFrontEndURL if SSL is configured

URI: It is of the format /identity/faces/adf.task-flow?_id=TASKFLOW_ID&_document=TASKFLOW_DOCUMENT . For example, /identity/faces/adf.task-flow?_id=request-approval-details-tf&_document=WEB-INF/oracle/iam/ui/custom/request-approval-details-tf.xml

19.8 Configuring Additional Request Form

Users can enter additional information for a request that can be useful for the request approvers.

This section contains the following topics:

19.8.1 Additional Request Information Concepts

Additional information about the request cart item or about the request itself can be provided during request submission. It may be required for request approval decisions when default form information is not sufficient.

The following features are supported with respect to additional information:

19.8.1.1 Additional Information for the Request Cart Item

With custom taskflows developed, users can provide additional information about the cart item (role/account/entitlement) when raising a request. You can provide additional information form about the request cart item as shown in the following sample screenshot.

Additional information icon for the cart item

When the user clicks the additional info icon (marked in red), a form is displayed with custom fields. The user can enter appropriate information that is useful for the request approvers.

The request approver can view and/or update additional request information provided at the cart item level. The request approver can access the request from Identity Self Service on the Inbox page or the Pending Approvals page.

19.8.1.2 Additional Information for the Request

There are instances where additional information about the request is required, for example additional information about the modify user request. Unlike additional information at cart item level, there is no explicit placeholder in the cart submission UI for this type of additional information. However, after developing a custom taskflow, you can customize the cart details page to create a link to show additional information about the request.

19.8.2 Understanding the Guidelines for Developing Custom Taskflow for Additional Request Information

Developing a custom taskflow for additional request information involves implementing custom taskflow for additional information, passing the input parameters when the taskflow is launched, saving and retrieving additional information in the managed bean, and using RequestFormContext to achieve the required customizations.

This section contains the following topics:

19.8.2.1 Implementing Custom Taskflow for Additional Request Information

To implement a custom taskflow that can be used for providing and viewing additional request information:

Develop the custom taskflow as a bounded taskflow in ViewController projects. For information about setting up the ViewController project, see Setting Up the ViewController Project. Specify the default package as oracle.iam.ui.custom.
Create a taskflow to render additional form. Make sure that the taskflow is in the WEB-INF/oracle/iam/ui/custom/ directory or its subdirectory, for example, /WEB-INF/oracle/iam/ui/custom/sample/catalog/tfs/additional-role-info.xml#additional-role-info.
Define taskflow input parameters as required. See Taskflow Input Parameters for information about the predefined input parameters that are passed when the taskflow is launched.
Deploy the taskflow as part of the oracle.iam.ui.custom shared library. For information about deploying the bounded taskflow, see Deploying Custom Code to Oracle Identity Governance.

19.8.2.2 Taskflow Input Parameters

The following table lists predefined input parameters that are passed when the taskflow is launched:

Parameter Name Type Description

Parameter Name	Type	Description
`additionalRequestInfo`	`oracle.iam.ui.common.model.catalog.requestdetails.AdditionalRequestInfo`	An instance of AdditionalRequestInfo interface. It is used to set and get values of additional request-level and cart item level request attributes. For more information about the interface methods, see Understanding the AdditionalRequestInfo Interface.
`requestFormContext`	`oracle.iam.ui.platform.view.RequestFormContext`	An instance of RequestFormContext. RequestFormContext provides various context information related to the request and currently selected cart item. For example, you can leverage the information provided by RequestFormContext to decide whether the input components of the custom taskflow must be rendered in read-only or editable mode. For more information, see Available EL Expressions in the RequestFormContext.

additionalRequestInfo

oracle.iam.ui.common.model.catalog.requestdetails.AdditionalRequestInfo

An instance of AdditionalRequestInfo interface.

It is used to set and get values of additional request-level and cart item level request attributes. For more information about the interface methods, see Understanding the AdditionalRequestInfo Interface.

requestFormContext

oracle.iam.ui.platform.view.RequestFormContext

An instance of RequestFormContext.

RequestFormContext provides various context information related to the request and currently selected cart item.

For example, you can leverage the information provided by RequestFormContext to decide whether the input components of the custom taskflow must be rendered in read-only or editable mode.

For more information, see Available EL Expressions in the RequestFormContext.

19.8.2.3 Saving and Retrieving Additional Information in Managed Bean Developed for the Project

The additionalRequestInfo pageFlowScope input parameter can be used to retrieve and store additional information about request or request cart item, as shown:

AdditionalRequestInfo additionalRequestInfo  =  (oracle.iam.ui.common.model.catalog.requestdetails.AdditionalRequestInfo) AdfFacesContext.getCurrentInstance().getPageFlowScope().get("additionalRequestInfo");

Note:

The oracle.iam.ui.common.model.catalog.requestdetails.AdditionalRequestInfo interface is described in Understanding the AdditionalRequestInfo Interface.

To set or get additional information about the request at the cart item level, use the following:

startDate = (Date additionalRequestInfo.getAttribute(cartItemId, START_DATE);
contractNumber = (String) additionalRequestInfo.getAttribute(cartItemId,  "CONTRACT_NUMBER" );

Similarly, to set the additional information at cart item level, use the following:

contractNumber = (String) additionalRequestInfo.setAttribute(cartItemId,  "CONTRACT_NUMBER" , "123");

Note:

To retrieve the current cart ID item selected in this context, use the requestFormContext pageFlowScope input parameter, as shown:

RequestFormContext requestFormContext = (oracle.iam.ui.platform.view.RequestFormContext) AdfFacesContext.getCurrentInstance().getPageFlowScope().get("requestFormContext");
cartItemId = requestFormContext.getUniqueCartItemIdentifier();

To set or get additional information about the request, use the following:

temporaryLocation = (String) additionalRequestInfo.getAttribute("TEMPORARY_LOC");
additionalRequestInfo.setAttribute("TEMPORARY_LOC", "A-24");

19.8.2.4 Understanding the AdditionalRequestInfo Interface

AdditionalRequestInfo interface extends Serializable as shown in the following code. Therefore, an instance of AdditionalRequestInfo can be stored in pageFlowScope of the custom taskflow.

public interface AdditionalRequestInfo extends Serializable {
    public void setAttribute(String name, Serializable value);
    public void setAttribute(String cartItemId, String name, Serializable value);
    public Serializable getAttribute(String name);
    public Serializable getAttribute(String cartItemId, String name);
}

To get or set the individual cart item additional information, use the following:

public void setAttribute(String cartItemId, String name, Serializable value);
public Serializable getAttribute(String cartItemId, String name);

The cartItemId parameter must be specified. You can use the getUniqueCartItemIdentifier EL expression in the RequestFormContext to access the selected cartItemId. For more information, see Available EL Expressions in the RequestFormContext.

To get or set the request level additional information, use the following:

public void setAttribute(String name, Serializable value);
public Serializable getAttribute(String name);

19.8.2.5 Using RequestFormContext to Achieve the Required Customizations

To distinguish between the various flows in which the taskflow is being launched (cart submission, request details, and approval details flows), you can rely on the requestFormContext parameter that is passed to the custom taskflow.

For instance, if you want to show the components of additional information taskflow to be in read-only mode for request summary, then use the following:

if  (requestFormContext.getActionType() == requestFormContext.ActionType.APPROVAL) {
    isFormUpdateable = Boolean.TRUE;
}

19.8.3 Configuring Custom Taskflow for Additional Request Information

Configuring custom taskflow for additional request information involves configuring custom taskflow for additional request information and configuring additional request information at request level.

This section contains the following topics:

19.8.3.1 Configuring Custom Taskflow for the Cart Item Level

The cart submission UI has explicit placeholders where the additional cart item information can be displayed.

You can enable users to provide additional information specific to a cart item, such as application instance, role, or entitlement. However, you are allowed to configure only one additional information taskflow per each entity type: role, entitlement, or application instance. This configuration is done with the help of the following system properties:

Catalog Additional Application Details Task Flow: Set the value to the custom additional information taskflow that is applicable to application instance entity type.
Catalog Additional Entitlement Details Task Flow: Set the value to the custom additional information taskflow that is applicable to entitlement entity type.
Catalog Additional Role Details Task Flow: Set the value to the custom additional information taskflow that is applicable to role entity type.

Note:

For more information on setting system properties, see Configuring Oracle Identity Manager in Administering Oracle Identity Governance.

For example, to launch a specific additional information taskflow for the role entity type, the value of the Catalog Additional Role Details Task Flow system property can be set as follows:

/WEB-INF/oracle/iam/ui/custom/sample/catalog/tfs/additional-role-info.xml#additional-role-info

The Cart Items table is displayed in the Cart Checkout, Request Summary, and Request Approval pages whenever the UI operation involves cart items. Clicking the cart item's additional info icon, the custom taskflow configured for cart entity type (such as role, application instance, entitlement) is displayed, as shown in the following sample screenshot:

19.8.3.2 Configuring Additional Request Information at Request Level

There are some scenarios when additional information is required at the request level, for example while submitting user modification request, where requester can provide additional information about user, and approver can review those. This feature is not available in the Identity Self Service by default, and must be implemented by developing custom taskflow, creating a sandbox, and UI customization, and establishing a link between the custom taskflow and the UI.

This section contains the following topics:

19.8.3.2.1 About Additional Request Information at Request Level

You can enable users to provide additional information specific to a request, such as Modify User request. To do so, you can add a link or a button to the catalog checkout page by customizing the UI. The newly added link or button can be made visible to Cart Checkout, Request Summary, and Request Approval pages. On clicking the link or button, you can invoke the popup to display the additional information about request.

A set of attributes defined as descendants of the component determine which custom taskflow is to be launched and how the popup window is displayed, as listed in Predefined Attributes to Determine the Custom Taskflow.

19.8.3.2.2 Predefined Attributes to Determine the Custom Taskflow

The following table lists the predefined attributes defined as descendants of the component that determine which taskflow is to be launched and how the popup window is displayed.

Name	Type	Required	Description
taskFlowId	java.lang.String	Yes	ID of the custom taskflow to be launched by the component.
dialogTitle	java.lang.String	Optional	Title of the popup window in which the custom taskflow is launched. If no value is specified, then the title is blank.
dialogTitleIcon	java.lang.String	Optional	Path to the icon that is displayed in the popup window in which the custom taskflow is launched. If no value is specified, then the default icon is used.

19.8.3.2.3 Sample Code for the Command Link

The following is a sample code snippet for the Command Link added through UI customization to invoke Additional Request Information popup:

Note:

For information about adding a Command Link through UI customization, see Adding a Link or Button.

<af:commandLink xmlns:af="http://xmlns.oracle.com/adf/faces/rich" id="e8065932664" text="Additional Cart Information" actionListener="#{catalogRequestBean.launchAdditionalRequestInfoTaskFlow}" rendered="#{backingBeanScope.additionalInfoHelperBean.renderAdditionalDetailsForRequest}">
         <af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="taskFlowId" value="#{backingBeanScope.additionalInfoHelperBean.additionalInfoTaskFlowIdForRequest}"/>
         <af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="dialogTitleIcon" value="/images/request_ena.png"/>
         <af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="headerText" value="Additional Cart Information"/>
         <af:clientAttribute xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name="dialogTitle" value="#{backingBeanScope.additionalInfoHelperBean.popupTitle}"/>
</af:commandLink>

In this sample code snippet, a custom Additional Cart Information link is added to cart details page. Here:

The actionlistener for the command link must be set to catalogRequestBean.launchAdditionalRequestInfoTaskFlow as follows:
```
actionListener="#{catalogRequestBean.launchAdditionalRequestInfoTaskFlow}"
```
The custom link can be selectively displayed for the rendered property by using the EL expression:
```
#{backingBeanScope.additionalInfoHelperBean.renderAdditionalDetailsForRequest}
```
To use this EL expression, develop a managed JAVA bean, such as additionalRequestInfoHelperBean, with the isRenderAdditionalDetailsForRequest method. This method returns a boolean value (true or false) based on whether the link has to be displayed or not. For more information about the managed bean, see Developing Managed Beans and Task Flows.
Launch different taskflows using the EL expression, #{backingBeanScope.additionalInfoHelperBean.additionalInfoTaskFlowIdForRequest}, specified as the value of the taskFlowId attribute. This is a mandatory attribute.

To use this EL expression, include the getAdditionalInfoTaskFlowIdForRequest method in the managed bean named additionalRequestInfoHelperBean. This method returns a String value representing the ID of the custom taskflow deployed as part of oracle.iam.ui.custom-dev-starter-pack.war, for example, /WEB-INF/oracle/iam/ui/custom/catalog/tfs/additional-cart-info-tf.xml#additional-cart-info-tf.
Set different popup window titles using the EL expression, #{backingBeanScope.additionalInfoHelperBean.popupTitle}, specified as the value of the dialogTitle attribute.

To use this EL expression, include the getPopupTitle method in the managed bean named additionalRequestInfoHelperBean. This method returns the desired String value to be displayed as the popup window title.

19.8.4 Validating Additional Request Information

If the additional request information has any mandatory attribute values to be submitted, then you can validate the submission by using a RequestDataValidator plug-in, which can validate RequestData.

The following is a sample configuration for the Assign Roles operation in the plugin.xml file while registering the validator plug-in. This configuration ensures that mycompany.iam.plugin.validation.AssignRolesDataValidator is invoked for all Assign Roles operations.

<plugins pluginpoint="oracle.iam.request.plugins.RequestDataValidator"> 
    <plugin pluginclass="mycompany.iam.plugin.validation.AssignRolesDataValidator" version="1.0" name="AssignRolesDataValidator">
           <metadata name="DataValidator">
                  <value>AssignRolesDataset</value> 
           </metadata>
    </plugin>
</plugins>

Similarly, for the Assign Entitlements operation, plugin.xml can be configured as follows:

<plugins  pluginpoint="oracle.iam.request.plugins.RequestDataValidator">
    <plugin  pluginclass="mycompany.iam.plugin.validation.AssignEntitlementsDataValidator"  version="1.0" name="AssignEntitlementsDataValidator">
           <metadata name="DataValidator">
                  <value> EBSForm.UD_EBS_RESP</value> 
           </metadata>
    </plugin>
</plugins>

19.9 Migrating UI Customizations

You can migrate UI customizations from one deployment to another by using incremental test to production (T2P).

Migrating UI customizations from one Oracle Identity Manager environment to another environment or test to production (T2P) is described with the help of the following scenario:

Scenario I: Incremental T2P

19.9.1 Scenario I: Incremental T2P

During the development cycle, you want to incrementally build configuration and keep moving the configuration from one Oracle Identity Manager setup to another.

To do this, you use the Deployment Manager, as described in Migrating Incrementally Using the Deployment Manager in Administering Oracle Identity Governance. But exporting and importing data using the Deployment Manager does not include the UI customization. For this reason, Oracle Identity Manager provides sandboxes, using which you can create customizations bound by sandboxes, test them, and eventually export/import them on an incremental basis.

However, incremental migration of customizations has a problem. You have to keep your sandboxes exported in advance, and then only publish the changes. But if you have already published the changes, then you cannot export. This is a known issue.

19.10 UI Customization Best Practices

Some best practices and guidelines must be followed for UI customization, such as creating sandboxes with detailed descriptions and exporting sandboxes before publishing.

This section describes some best practices and guidelines related to UI customization. It contains the following topics:

19.10.1 Create Sandboxes With Detailed Description

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.

19.10.2 Create a Backup of MDS Before Publishing a Sandbox

Create a backup of MDS before publishing a sandbox.

Before publishing a sandbox, create a backup of MDS so that the earlier state of MDS can be restored if anything goes wrong.

19.10.3 Migrate All Sandboxes to the Target Environment and Publish in the Same Order

All the sandboxes that have been published in the first environment (or source environment) must be migrated and published in the second environment (or target environment), and the sandboxes must be published in the same order.

If this guideline is not followed, then some of the customizations will be missing in the target environment resulting in ADF errors or missing attribute display labels.

Migrating sandboxes from multiple source environments into a single target environment is not supported. See sections Handling Concurrency Conflicts and Troubleshooting Concurrency Issues for detailed information about various scenarios.

19.10.4 Export the Sandbox Before Publishing

If you are planning to migrate customizations from one environment to another, then all the sandboxes must be exported before publishing.

It is not possible to export a sandbox that has already been published.

19.10.5 Test the Sandbox Before Publishing

Publish a sandbox only after testing of related use cases.

The main purpose of using sandboxes is to be able to experiment with customizations. Therefore, publish a sandbox only after thorough testing of related use cases. After the sandbox is published, it cannot be unpublished easily. This also applies to migration of sandboxes to another environment, where the sandbox must be published only after sanity testing.

19.10.6 Do Not Change Default Component IDs

Treat the IDs of default components as read-only.

It is possible to view and edit component IDs by using WebCenter Composer, as shown in Figure 19-15.

Figure 19-15 Component ID

Description of "Figure 19-15 Component ID"

Note that changing IDs of default components on system-defined pages must be avoided. Component ID must be treated as read-only. It can be used, for example, in the Partial Triggers property of another component if the component is supposed to be re-rendered based on changes or when click to the component is being referenced.

19.10.7 Use Discretion When Deleting Components From a Page

Exercise caution when deleting system-defined components from pages, especially when the component binding property is set.

These components can be referenced from the managed beans shipped with Oracle Identity Manager, and removing the component from the page will result in bindings not being set. This can lead to errors, such as NullPointerException. In such instances, it is preferable to hide the component from the page by setting the Visible property to false.

Note that marking a component as not being rendered (deselected Show Component option) has the same effect on component bindings, which means it will not be set.

19.10.8 Note That Direct Changes to Default EOs/VOs Are Not Supported

Making any direct changes, such as exporting the EO/VO XML from MDS and modifying it, to system-defined EOs/VOs, such as UserVO, OrganizationVO, and RoleDetailsVO, is not supported.

The Form Designer, which accessed via User, Organization, Role, or Catalog system entities links in the Identity System Administration, is the only supported way of adding new attributes or modifying existing ones.

19.10.9 Specify Name Space for JSFF Tags

If you are manually adding JSFF components in an exported sandbox, then specify name space for each of the JSFF tags.

The following code snippet shows an example customization document where new af:outputText is being added:

<?xml version='1.0' encoding='UTF-8'?>
<mds:customization version="11.1.1.66.49" xmlns:mds="http://xmlns.oracle.com/mds" motype_local_name="root" motype_nsuri="http://java.sun.com/JSP/Page">
   <mds:insert parent="sdh1" position="first">
      <af:outputText value="Some text" id="e7869964958"/>
   </mds:insert>
</mds:customization>

Note that there is no name space specified for af:outputText. Such code snippet will cause java.io.IOException: Stream closed when user opens the page. No exception is thrown during sandbox import or when activating the sandbox. The exception is thrown only when the page is being accessed.

The following code snippet shows the corrected af:outputText with xmlns:af="http://xmlns.oracle.com/adf/faces/rich" name space specified:

<?xml version='1.0' encoding='UTF-8'?>
<mds:customization version="11.1.1.66.49" xmlns:mds="http://xmlns.oracle.com/mds" motype_local_name="root" motype_nsuri="http://java.sun.com/JSP/Page">
   <mds:insert parent="sdh1" position="first">
      <af:outputText xmlns:af="http://xmlns.oracle.com/adf/faces/rich" value="Some text" id="e7869964958"/>
   </mds:insert>
</mds:customization>

19.10.10 Note That Customizations Are Only Allowed in Site/Site Layer

If you are manually editing an MDS customization document, for example, in an exported sandbox, then you are only allowed to edit documents in the site/site customization layer.

All other customization layers, such as site/oim, edition/xe, and edition/ee, must not be used.

You can find out from the document path which layer the document resides in. For example, the oracle/iam/ui/myinformation/pages/mdssys/cust/site/site/my-info.jsff.xml document resides in the site/site layer. The layer name is specified after mdssys/cust.

All the customizations made by using WebCenter Composer are stored in the site/site layer. Home page personalizations and other personalizations are stored in user/USER_NAME layer. While personalization documents can be manually edited, they are only applicable to the USER_NAME user.

19.10.11 Note That Each Application Instance or Entitlement Form Has Three Page Fragments (JSFF)

Each application instance or entitlement form has create, modify, and bulk page fragments.

Every application instance or entitlement form has the following page fragments (JSFF):

create: Displayed when requesting for application instance or entitlement
modify: Displayed when modifying existing application instance or entitlement; also used when viewing application instance or entitlement details on application instance or entitlement pages in user profile and My Access sections of Identity Self Service
bulk: Displayed for bulk requests

Whenever you are customizing the application instance or entitlement form, you typically want to customize all three page fragments (JSFF), or at least create and modify page fragment. Create page fragment can be customized when requesting for application instance or entitlement, and modify page fragment can be customized when modifying existing application instance or entitlement. All three page fragments are regenerated when you click the Regenerate View button in the Form Designer.

19.10.12 Use Discretion When Using the Searchable Picklist Option

Select the Searchable Picklist option only if you are planning to use Input List of Values component when adding the UDF to the page.

When creating lookup UDFs you have an option to select the Searchable Picklist option. This option must be checked only if you are planning to use Input List of Values component when adding the UDF to the page, which you must decide at the time of creating the UDF because the value of Searchable Picklist cannot be changed later. If you decide to select the Searchable Picklist option, then there is an additional VO attribute created. The attribute is suffixed with __c_Id__c and is for internal use only. When adding the UDF to the page, select and add the regular attribute, not the one with __c_Id__c suffix.

If you did not select the Searchable Picklist option, then the correct component to choose when adding the UDF to the page is Select One Choice and not Input List of Values.

19.10.13 Sign-out After Adding/Updating UDF

You must sign-out from Identity Self-Service or Identity System Administration after adding new or updating existing UDF. This is to avoid known caching issue in ADF layer wherein older version of the VO is being cached and new changes are not being picked up.

If you forget to sign-out and go directly to the page where the VO is being used, you will see an error similar to JBO-25058: Definition MyUDF__c of type Attribute is not found in UserVO, or you will not be able to select the UDF in WebCenter Composer catalog while adding the UDF to the page.

19.10.14 Verify the UDF After Adding it to the Page

Make sure to create the UDF properly and use the correct Data Component and VO when adding the UDF.

If you add a UDF to the page and the UDF is not working, for example the input component is shown as read-only although it should be editable or the provided UDF value is not being properly saved, then you can verify the following:

Make sure that you use the right Data Component and VO when adding the UDF to the page, as described in Entities and Corresponding Data Components and View Objects in Administering Oracle Identity Governance.
Check if the UDF has been properly created. For the UDF that is created, there must be a column created in the corresponding database table, for example in the USR table for User UDF, and corresponding dataset must be updated, for example User.xml for User UDF.

If any of these have not been or is missing, then the UDF is not properly created and must be created again.

If you forget to set autoSubmit=true and set valueChangeListener on the UDF component, as described in Adding a Custom Attribute in Administering Oracle Identity Governance, then the UDF works but the Save/Cancel or Apply/Revert buttons are not enabled.

19.10.15 Map UDF With Correct LDAP Attribute

Map the UDF with the correct LDAP attribute.

While creating a UDF in Oracle Identity Manager deployment in LDAP mode, map the UDF with the correct LDAP attribute.

19.10.16 Deploy Custom Managed Beans as Part of the oracle.iam.ui.custom-dev-starter-pack.war Shared Library

When introducing custom managed beans, the beans must be deployed as part of the oracle.iam.ui.custom-dev-starter-pack.war shared library.

Recommended scope of the custom managed beans is either pageFlowScope or backingBeanScope. Avoid defining custom beans in sessionScope and consider using pageFlowScope instead. The pageFlowScope bean class must be serializable. Implement java.io.Serializable interface and all the class fields must be serializable as well. Note that component bindings, such as RichOutpuText, are not serializable, and therefore, must be defined in backingBeanScope bean. If you are implementing a custom task flow, then the recommended practice is to have two managed beans:

pageFlowScope bean, which holds the state of the taskflow (if any).
backingBeanScope bean for component bindings actionListeners (or listeners in general). The backingBeanScope bean can access pageFlowScope bean and its properties via an EL, not vice versa.

19.10.17 Consider Replacing the Entire Taskflow

If you want to significantly change the default look and feel of the page, then it might be beneficial to completely re-implement the entire taskflow.

This way it is guaranteed that your custom taskflow will work even after upgrading Oracle Identity Manager. This may not be true if you significantly customize one of the predefined pages. Although Oracle Identity Manager UI customizations are upgrade-safe, there are exceptions to this when customizations are broken or lost post-upgrade. This is because it is sometimes not possible to retain customizations if the flow changes completely.

If you decide to re-implement the entire taskflow, then you can add a new Home page tile on one of the Home pages to launch the new taskflow and hide the original tile by launching a default taskflow. See Adding a Tile to the Home Page for more information about adding a tile to the Home page..

19.10.18 Do Not Update Oracle Identity Manager WAR/EAR Files

Note the WAR/EAR files that you can update.

You must not updated the following WAR/EAR files:

oracle.iam.console.identity.self-service.ear
oracle.iam.console.identity.sysadmin.ear
oracle.iam.ui.view.war
oracle.iam.ui.oia-view.war
oracle.iam.ui.model.ear

Any changes to one of these WAR/EAR files are lost during upgrade.

The only WAR file that you can update is oracle.iam.ui.custom-dev-starter-pack.war. In fact, this WAR file is intended for use in customizations, such as in custom managed beans, resource bundles, and taskflows. Changes to oracle.iam.ui.custom-dev-starter-pack.war are retained during upgrade.

19.10.19 Consider Conditionally Showing Certain Home Page Tiles

By default, all the home page tiles are displayed. However, you might want to consider hiding some of the tiles from certain users to prevent them from accessing the pages.

For example, you might want to hide the Provisioning Tasks tile for end users. See Showing Tiles Conditionally for information about showing tile based on conditions.

19.10.20 Do Not Invoke Platform APIs From Custom Managed Bean

Invoking Platform APIs directly by using Oracle Identity Manager data source in custom managed bean is not supported.

Only Public APIs that are exposed through OIMClient can be invoked.

19.10.21 Use Recommended Value of Display Width While Creating Lookup UDFs

Use the recommended value of the Dislpay Width field.

While creating lookup type UDF, the recommended value of the Display Width field is 40.