19 Customizing the Interface
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:
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:
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:
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:
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.
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:
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:
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:
-
Login to Oracle Identity Self Service as an administrator with privileges to customize the UI.
-
In an active sandbox, click the Customize link. The Oracle Identity Self Service is in customization mode.
-
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.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:
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:
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:
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:
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.
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:
19.3.12.2 Adding Custom Attributes to the Certification Table
To create a UDF and add it 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.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:
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.
-
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:
-
Select the Panel Grid Layout component as shown in Figure 19-8.
-
Click the Add icon.
-
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.
-
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:
-
Select the Panel Grid Layout component, as shown in Figure 19-8.
-
Using the Component tree on the right, select one of the child grid rows where you want to add a new grid cell.
-
Click the Add icon.
-
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.
-
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:
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:
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:
-
Start JDeveloper.
-
Select File, New.
-
Select Generic Application, and then click OK.
-
Provide the application name and directory, and then click Finish. The application is created using a sample project.
-
To delete the sample project, right-click the project, and select Delete.
-
-
Setup the ViewController project. To do so:
-
Select File, New.
-
Find and select ADF ViewController Project, and then click OK.
-
Provide the project name, for example CustomUI, and project directory, and then click Next.
-
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:
-
Right-click the new project, and select Project Properties.
-
On the left navigation bar, select Libraries and Classpath.
-
Click Add Library. Add ADF Model Runtime.
-
Click Add Library, click Load Dir, provide the path as IDM_HOME/server/jdev.lib, and then click OK.
-
From the list of libraries, select the following:
-
OIM View Shared Library
-
OIM Model Shared Library
-
OIM Client Library
-
-
Click OK.
-
-
Define the deployment profile for the newly created ViewController project. To do so:
-
Right-click the project, and select Project Properties.
-
On the left navigation bar, select Deployment.
-
Delete any existing deployment profiles.
-
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.
-
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:
-
Right-click the project, and select Project Properties.
-
On the left navigation bar, select Libraries and Classpath.
-
Click Add Library.
-
Click Load Dir, provide the path as IDM_HOME/server/jdev.lib, and then click OK.
-
From the list of libraries select the following:
-
OIM Model Shared Library
-
OIM Client Library
-
-
Click OK.
-
-
Define the deployment profile for the newly created model project. To do so:
-
Right-click the project, and select Project Properties.
-
On the left navigation bar, select Deployment.
-
Delete any existing deployment profiles.
-
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.
-
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:
-
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.
-
Click the Overview tab, and select Managed Beans.
-
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:
-
Set component bindings for the User Type list and root panel components to point to the properties that you defined.
-
Define the valueChangeListener for the User Type list.
Note:
Make sure that the autosubmit property is set to true for the User Type list.
-
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:
-
Set the component bindings for First Name, Last Name, and root panel to point to the properties that you defined.
-
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:
-
Set component bindings for the User Type list and root panel components to point to the properties you defined.
-
Define valueChangeListener for the User Type list. Make sure that the autosubmit property is set to true for the User Type list.
-
Set EL expression for the required property on the Manager field to point to the isInternUserTypeSelected() method defined is step 3.
-
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:
-
Set component bindings for the Start Date and End Date fields to point to the properties that you defined.
-
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.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:
-
Add a Prepopulate button to the Create Application Instance form.
-
Set bindings for the Prepopulate button and the root panel.
-
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:
-
Export the sandbox.
-
Edit the JSFF to set the actionListener attribute value. For example:
<mds:attribute name="actionListener" value="#{backingBeanScope.accountFormReqBean.submitButtonActionListener}"/>)
-
Import the updated sandbox.
This procedure is applicable to setting the actionListener property in all the examples in this document.
-
-
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:
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:
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.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:
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:
19.7.8.1.6 Configuring the Properties of the Prepopulate Button
To manually configure the properties of the Prepopulate button:
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:
|
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.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.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.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.
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 |
---|---|---|
|
|
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. |
|
|
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 theisRenderAdditionalDetailsForRequest
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 thetaskFlowId
attribute. This is a mandatory attribute.To use this EL expression, include the
getAdditionalInfoTaskFlowIdForRequest
method in the managed bean namedadditionalRequestInfoHelperBean
. This method returns a String value representing the ID of the custom taskflow deployed as part oforacle.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 thedialogTitle
attribute.To use this EL expression, include the
getPopupTitle
method in the managed bean namedadditionalRequestInfoHelperBean
. 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:
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:
-
Migrate All Sandboxes to the Target Environment and Publish in the Same Order
-
Note That Direct Changes to Default EOs/VOs Are Not Supported
-
Note That Customizations Are Only Allowed in Site/Site Layer
-
Note That Each Application Instance or Entitlement Form Has Three Page Fragments (JSFF)
-
Deploy Custom Managed Beans as Part of the oracle.iam.ui.custom-dev-starter-pack.war Shared Library
-
Use Recommended Value of Display Width While Creating Lookup UDFs
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.
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 bindingsactionListeners
(or listeners in general). ThebackingBeanScope
bean can accesspageFlowScope
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.