Sun Identity Manager Deployment Reference

Understanding Forms

To customize Identity Manager’s Web-based user interface appearance and function, you must modify the form associated with the web page you want to edit.

The term form can describe both the web page where users enter information and the object that contains rules about how to display data in the view. Throughout this guide, the term form typically refers to the object that contains rules about how to display data in the view.

This section covers the following topics:

What Are Forms?

A form is an object associated with a page that contains rules about how the browser should display user view attributes on that page. Forms can incorporate business logic and are often used to manipulate view data before it is presented to the user.

For example, to create a new user account, you use the Create User page, in which you enter information about the new user. This page is generated using an object (a form) in the Identity Manager repository named Tabbed User Form. This form specifies which fields are visible on the Create User page and which HTML form element (for example, text box, check box, or select box) is used to represent each field. This form also specifies additional logic for disabling fields, populating empty fields with default values, and calculating field values from the values of other fields.

What Forms Control

Forms control the following objects and activities:

Sample Form

The following XML example defines the form fields that are used by users to enter account ID, first name, last name, and full name. It specifies how the user’s full name is built out of the information entered into the First Name and Last Name fields.

<Field name=’waveset.accountId’/>
   <Display class=’text’>
     <Property name=’title’ value=’AccountID’/>
<Field name=’global.firstname’>
   <Display class=’Text’>
      <Property name=’title’ value=’First Name’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’128’/>
<Field name=’global.lastname’>
   <Display class=’Text’>
      <Property name=’title’ value=’Last Name’/>
      <Property name=’noNewRow’ value=’true’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’128’/>
<Field name=’global.fullname’>
   <Display class=’Text’>
      <Property name=’title’ value=’FullName’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’32’/>
            <s> </s>

Why Edit Forms?

Why customize the default Identity Manager pages, which already provide all the fields that you need to perform actions within the product? Customizing the default forms allows you to better enforce your company’s policies and processes:

Customizing the default fields in Identity Manager forms allows you to extend and customize the application for your environment. Specifically, you can customize the default forms to:

Example Scenario

Forms are especially useful in environments where people with varying needs and purposes must access the same data.

For example, you can create a form that hiring managers at your company will use to create a new employee account. The default Tabbed User Form displays more information than the hiring managers need. Rather than displaying all 99 fields in a distractingly busy form that might complicate the user’s task, you can create a form in which the hiring managers must fill in only 10 attribute fields and the other 89 attributes are set based on rules that you, the administrator, define.

Identity Manager Pages that Use Forms

Identity Manager forms are typically classified into one of two categories:

The following table shows some of the Identity Manager pages that use forms of the first type. Use this table to identify the form that controls the display characteristics of the page you want to edit.

Table 2–1 Pages and Associated JSPs and Forms

Page You Want to Edit 

Associated JSP 

Associated Form 

Create/Edit User 


Tabbed User Form 

Change User Account Attributes 


End User Form 



Anonymous User Menu 

Edit Work Item 


Approval Form 

Edited Forms

Of the default forms that ship with Identity Manager, you will probably edit one of the following five forms:

These edited forms control the creation and modification of users and the display of the main menu that the user sees. They are described in greater detail in the following sections.

Note –

During view and form interactions through the Administrator Interface JSPs for launching requests (before workflow launch), the view is edited directly. Consequently, the form runs in the namespace specified by the form attribute. Typical attribute namespaces include:

Change Password Forms

By default, there are two implementations of the Change Password forms:

Both Password Change forms support the use of the RequiredChallenge form property. When this property is set to true, the user is prompted to enter the old password after specifying the new password. See Adding a Password Confirmation Challenge for more information.

End User Menu Form

End User Menu Form controls the display of the main menu in the Identity Manager User interface. Typically, this form contains links for changing the user’s password, editing account attributes, and changing answers to authentication questions.

You can customize End User Menu Form to add links to launch special workflow processes that are accessible to the user (for example, a process to request access to a system).

Note –

You can set the RequiresChallenge property in the End User Interface Change Password Form to require users to reenter their current password before changing the password on their account. For an example of how to set this property, see the Basic Change Password Form in enduser.xml.

For example, to present the End-User Test Process as a link to click from the end- user pages, add the entries shown in the following code example:

Example 2–1 Adding End-User Test Process link to End User Menu Form

<Configuration id=’#ID#Configuration:EndUserTasks’ name=’End User Tasks’>
         <String>End-User Test Process</String>
         <String>An example end-user workflow</String>

The Identity Manager User Interface displays a list of self-service processes for selection. This is expected to be a list of lists. The first element of the sublist displays the process name, and the second element describes what the process does.

Note –

Identity Manager re-evaluates this form’s <Default> expressions whenever the page is refreshed. You can disable this forced regeneration of the form by adding the doNotRegenerateEndUserMenu property (set to true) on the End User Menu form.

Identity Manager re-evaluates this form’s <Default> expressions whenever the page is refreshed. You can disable this forced regeneration of the form by adding the doNotRegenerateEndUserMenu property (set to true) on the End User Menu form as follows:

   <Property name=’doNotRegenerateEndUserMenu’>

Anonymous User Menu Form

Anonymous User Menu Form controls the display of the main menu in the Identity Manager User interface when an unknown user logs in.

Identity Manager uses the anonymous end user pages for users who are not defined in the system through the process of user self-provisioning. For example, an Identity Manager administrator can set up pass-through authentication for an Active Directory resource. As a result, any person who has an Active Directory account can log in to the Identity Manager User interface. You can customize those pages so that when a user who does not have a Identity Manager account logs in, an Identity Manager user object is created and the Active Directory resource is added. Subsequently, through a series of questions, the system can set up the user’s role, organization, and other resources.

You can customize Anonymous User Menu Form to launch workflow processes to request services before an Identity Manager user exists.

Tabbed User Form

Tabbed User Form is the default form used for user creation and modification in the Identity Manager Administrator Interface. You can customize a copy of this form by extending it with a form of your design.

Tip –

Do not directly edit the Tabbed User Form. Instead, Sun recommends that you make a copy of this form, give it a unique name, and edit the renamed copy. This will prevent your customized copy from being overwritten during service pack updates and upgrades.

Customize your copy of Tabbed User Form to:

Tabbed User Form contains these fields:

Note –

Do not use the MissingFields element in a production environment. It is provided for educational purposes only.

When creating or customizing a User form from the Tabbed User form, you must replace the MissingFields element with explicit references to each individual attribute that can be pushed to the assigned resource. You must provide this replacement to avoid common pitfalls that can result from using the global namespace too heavily. (For example, your workflows will not populate resources unless they use global syntax.)

(The MissingFields field is not actually a field. It is an element that indicates to the form generator that it should automatically generate text fields in the global namespace for all attributes that can be pushed to the assigned resources that are not explicitly declared in the Tabbed User Form.)

By default, every attribute defined on a resource that is assigned to a user appears on the Create User and Edit User pages as a text box (or checkbox for Boolean values).

End User Form

End User Form controls the page that the system displays when a user selects Change Other Attributes from the /user/main.jsp on the Identity Manager User interface. From this page, a user can change his password, authentication questions, and email address.

You can customize End User Form to grant users control over other fields, such as those that handle phone numbers, addresses, and physical office locations.

Approval Form

Approval Form controls the information that is presented to a resource, role, or organization owner when he is designated an approver of user requests. By default, this page displays a set of read-only fields that contain the name of the administrator that started the process. It also displays information about the user, including the account ID, role, organization, and email address.

This form ensures that the resource owner gets a last chance to change a user value before the user is created. By default, approving a user displays all the user attributes in read-only fields.

You can customize Approval Form to:

How Do Forms Work?

Various factors affect how the browser displays a form. However, form behavior within the browser is primarily determined by:

User View and Forms

The user view is a data structure that contains all available information about an Identity Manager user. It includes:

Views contain many attributes, and a view attribute is a named value within the view (for example, waveset.accountId is the attribute in the user view whose value is the Identity Manager account name).

Most form field names are associated with a view attribute. You associate a field with a view attribute by specifying the name of the view attribute as the name of the form field. For more information, see Field Display Properties.

For more information about the user view, including a reference for all attributes in the user view, see Chapter 3, Identity Manager Views

Undefined Attributes

When a resource or role is assigned to a user through the administrative interface, a refresh occurs. The new resource account attributes are then defined in the User view. <FormRef name = ’Missing Fields’/> in the Tabbed User Form indicates to the form generator that text fields should be generated for any resource account attributes that do not have a corresponding field explicitly defined in the form. To disable this feature in the Tabbed User Form, delete <FormRef name = ’Missing Fields’/>.

Form Evaluation

How the system processes a form helps determine the behavior of the form in the browser. All form-driven pages are processed similarly, as described below:

  1. A page is requested from the Identity Manager User or Administrator Interface.

  2. The interface requests a view from the server. A view is a collection of named values that can be edited. Each view is associated with a form that defines how the values in the view are displayed to the user.

  3. The server assembles a view by reading data from one or more objects in the repository. In the case of the user view, account attributes are also retrieved from resources through the resource adapter.

  4. Derivation expressions are evaluated. These expressions are used to convert cryptic, encoded values from the resource into values that are more meaningful to the user. Derivations are evaluated when the form is first loaded or data is fetched from one or more resources.

  5. Default expressions are evaluated. These fields are set to the default value if the field is null.

  6. HTML code is generated. The system processes view data and the form to produce an HTML page. During this processing, the allowedValues properties within expressions are evaluated to build Select or MultiSelect HTML components.

  7. The page is presented in the browser, and the user can edit the displayed values. During editing, the user typically modifies fields, which can result in a refresh or recalculation of the page. This causes the page to be regenerated, but the system does not yet store the edited data in the repository.

  8. Modified values are assimilated back into the view. When a refresh event occurs, the interface receives values for all the form fields that were edited in the browser.

  9. Expansion expressions are evaluated. This can result in additional values being placed into the view. Expansion rules are run whenever the page is recalculated or the form is saved.

  10. The view is refreshed. The interface asks the server to refresh the view and provides the current set of edited values. The server may insert more values into the view by reading data from the repository or the resources.

  11. Derivation expressions are evaluated. Typically, derivation expressions are not evaluated when a view is refreshed. In some complex cases, the system can request derivations after the refresh.

  12. The system processes the refreshed view and form and builds another HTML page, which is returned to the browser. The user sees the effects of the refresh and continues editing. The user can cause the view to be refreshed any number of times (repeating steps 7 through 12 each time) until the user either saves or cancels the changes.

    1. If the edit is canceled, all the data accumulated in the view is discarded, and the server is informed. As a result, the server can release any repository locks, and control passes to a different page.

    2. If the edit is saved, the interface receives the values that have been modified and assimilates them into the view (see step 8).

  13. Validation expressions are evaluated. If field values do not meet required specifications, then an error is presented and the field values can be corrected. Once the changes have been made, the process returns to step 13.

  14. Expansion expressions are evaluated one last time (see step 9).

  15. If the server saves the view, this typically results in the modification of one or more objects in the repository. With user views, resource accounts may also be updated.

Several of the preceding steps require iteration over all the fields in the form. These include the evaluation of Derivation expressions, the evaluation of Default and Validation expressions, the generation of HTML, and the evaluation of Expansion expressions. During all field iterations, Disable expressions are evaluated to determine if this field should be processed. If a Disable expression evaluates to true, the field (and any nested fields it contains) is ignored. See Defining Field Names in this chapter for more information on these special types of expressions.

Empty Forms

An empty form is a form that contains no fields that you can deploy to prevent changes from being applied to the User view during form processing.

Example 2–2 Empty Form Object

<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’>
<Configuration wstype=’UserForm’name=’Empty Form’>
      <Form name=’Empty Form’>
      <ObjectRef type=’ObjectGroup’ name=’Top’/>

You can implement an empty form as an alternative to MissingFields. MissingFields attempts to perform its function across the Accounts list in the User view. In contrast, an empty form effectively prevents any changes being applied to the User view during form processing.

When to Use an Empty Form

Use an empty form when

Using Empty Form during Active Sync Processing

The use of an empty form is an integral part of successful Active Sync processing.

When Identity Manager processes records from the Active Sync resource, it uses either the default form configured for the system (Tabbed User form) or the form, if any, that has been defined for the administrator account.

Because the default Tabbed User Form can have undesired effects on data from the Active Sync resource, best practice suggests creating an empty form and assigning it directly to the proxy administrator rather than using the default form.

Note –

You should directly associate the empty form to the proxy administrator and not through an Admin Role. Setting the empty form at the Admin Role level causes the Tabbed User Form to be invoked during Active Sync processing.