7 Customizing Field Behavior and Functionality

This chapter describes how to customize the behavior of the various fields that appear within your Oracle Identity Manager Administrative and User Console. You can customize that behavior in the following ways:

• Edit the system fields that appear on the Administrative and User Console pages.

• Add new user-defined fields.

• Control who has the ability to edit the values in various fields.

This chapter contains these topics:

• About the FormMetaData.xml File

• Defining a New Field

• Files to Modify

• Setting Field Configuration

About the FormMetaData.xml File

Use the FormMetaData.xml file to define form controls and labels in the Administrative and User Console. You can also edit how the default fields behave, for example, you can make them viewable, editable or required. For all entries in the FormMetaData.xml file, the attributes section defines the fields included in the pages while the attribute references sections define the fields on a particular page or group of pages. To define a new value property for this file, you must define the attribute, and then reference it for a page.

The following table lists the forms that are depending on the FormMetaData.xml file.

FormMetaData.xml File Sections
<!-- User Self Registration and User Profile Modification section -->
User self-registration form	<Form name="SelfRegistrationUserForm">
Self-registration Approval form	<Form name="SelfRegistrationApprovalForm">
User profile modification form	<Form name="ProfileModificationUserForm">
User profile modification Approval form	<Form name="ProfileModificationApprovalForm">
<!-- User Management section -->
User form	<Form name="3">
Group form	<Form name="6">
<!-- Organization Management section -->
Organization form	<Form name="2">
<!-- Resource Management section -->
Resource form	<Form name="5">

The pages on which you can customize field behavior are listed here:

Page	How it is accessed
User Detail	Use the Manage link under Users, then execute a query and select a particular user account.
Create User	Use the Create link under Users.
User Self Registration	Use the Create Request link under Self-Registration.
Modify Account Profile	Use the Account Options link. Then click Modify Account Profile.
Edit User	Use the Manage link under Users, then execute a query and select a particular user account. Then, click the Edit button at the bottom of the User Detail page.
Create User Request	Use the Track link under Requests, then execute a query and select a particular request (of type Self-Registration). Expand the User Information branch and click Provide User Information.
Organization Detail	Use the Manage link under Organizations, then execute a query and select a particular organization.
Create Organization	Use the Create link under Organizations.
Group Detail	Use the Manage link under User Groups, then execute a query and select a particular user group.
Create User Group	Use the Create link under User Groups.
Resource Detail	Use the Manage link under Resource Management, then execute a query and select a particular resource.

Note: Any pages that are not listed in the preceding table obtain their label names from the xlWebAdmin.properties file or the corresponding locale-specific properties files.

For each of these pages, Oracle Identity Manager is preconfigured with certain system fields. In addition, you can define the user-defined fields to be displayed on these forms as well. The behavior of either of these types of fields can be customized for the pages listed here. However, the procedure for customizing their behavior differs depending on whether the field is a system-defined field or user-defined field.

Note: All user-defined fields must first be defined by using the User Defined Field Definition form of the Oracle Identity Manager Java Client as explained in Oracle Identity Manager Design Console Guide. Once you have created the user-defined field within the Oracle Identity Manager Java Client, you then also add it to the list of attributes in the section <!-- User Self Registration and User Profile Modification section -- > of the FormMetaData.xml file. Do not add it to the list in the <! --User Management -- > section of that file. Ensure that your attribute entry provides values for each of the following parameters: Name—Must be same as column name for this field in the Java Client Label—does not need to conform to label specified for this field in the Java Client DisplayComponentType—Must be same as the value of Field Type for this field in the Java Client DataLength—Must be same as the value of Length for this field in the Java Client Map—Must be same as column name for this field in the Java Client) Make the entry for the user-defined field consistent with the definition of the field in the Oracle Identity Manager Java Client.

Defining a New Field

To define a new field for the Console:

1. Create the field definition by using the Java Client. Note this information for use in editing the FormMetaData.xml file.

2. Define the attribute in the FormMetaData.xml file.

   To define the attribute, add an entry for it using the same information you entered when you used the Java Client to create a field definition. To do this, you specify the following information:

   <Attribute name="identifier" label="field_label" displayComponentType="datatype"            map="identifier" />
   
   

   where

   • Attribute name is the identifier used to specify this field. This is the name used to specify this field on a page.

   • label specifies the associated property name in the xlWebAdmin.properties file or the locale-specific file.

   • displayComponentType is the data type of the field displayed in the Console.

   • map is the database column name specified when you created the field definition using the Java Client. User-defined fields are prefixed with USR_UDF_, so if you typed in SSN in the Java Client, this value is USR_UDF_SSN.

     For example:

     <Attribute name="social" label="SSN" displayComponentType="TextField"                map="USR_UDF_SSN" />
     
     

3. Reference the attribute in the FormMetaData.xml file in the section for the page on which you want the field to appear.

Files to Modify

To customize field behavior and functionality, you edit the following file: FormMetaData.xml.

Setting Field Configuration

This section explains how to configure fields in various pages. It contains these topics:

• For Fields in the User Detail, Create User, and Edit User Pages

• For Fields in the User Self Registration, Create User Request, and Modify Account Profile Pages

• Example: Setting the User ID Field on the Create User Request Page

For Fields in the User Detail, Create User, and Edit User Pages

Fields available for use within the Create User, User Detail, and Edit User pages are controlled by the attribute definition within the <!-- User Management section -- > of the FormMetaData.xml file.

Fields displayed on each of these pages are controlled by using the attribute references in the <!--Fields that will be displayed on the Users form section-- > section of the FormMetaData.xml file

For each attribute reference, you can specify whether the field is:

• Viewable—By adding the attribute reference to the relevant section

• Editable—By specifying a value of TRUE or FALSE for the editable parameter

• Optional—By specifying a value of TRUE or FALSE for the optional parameter

Note: You do not need to add an attribute definition or attribute references for user-defined fields associated with these pages.

For Fields in the User Self Registration, Create User Request, and Modify Account Profile Pages

The fields in the User Self Registration, Create User Request, and Modify Account Profile pages are controlled by the attribute definition within the <!-- User Self Registration and User Profile Modification section -- > of the FormMetaData.xml file. The fields that appear on each of these pages are controlled by using the attribute references in the following sections of the FormMetaData.xml file

Section	Page Affected
<Form name="SelfRegistrationUserForm">	User Self Registration
<Form name="SelfRegistrationApprovalForm">	Create User Request
<Form name="ProfileModificationUserForm">	Modify Account Profile

For each attribute reference, you can specify whether the field is:

• Viewable—By adding the attribute reference to the relevant section

• Editable—By specifying a value of TRUE or FALSE for the editable parameter

• Optional—By specifying a value of TRUE or FALSE for the optional parameter

Example: Setting the User ID Field on the Create User Request Page

This example shows how to make the system field User ID on the Create User Request page viewable, editable, and required.

1. Open the FormMetaData.xml file

2. Locate the section <!-- Definition of the form that will be displayed to the approver(s) for self registration approvals -- >.

3. Add an attribute reference to this sectionto represent behavior of this field on the Create User Request page:

   <AttributeReference editable="true" optional="false"> 
   Users.User ID
   </AttributeReference>
   
   

   This entry causes the User ID field to be visible, editable, and required on the Create User Request page.

   
   

   Note: To edit the label applied to a field, edit the value of the label parameter of the applicable attribute definition.