What Are Forms? (Sun Identity Manager Deployment Reference)

Sun Identity Manager Deployment Reference

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:

Layout and display characteristics of the page

Forms are composed of fields. Visible field types include simple text boxes, radio buttons, and selection boxes with multiple values. Fields can also have values based on other fields and can be either read-only or be hidden from view.
Data that is used on the page

Data can be captured dynamically from a resource or be calculated from other fields. With the Identity Manager expression language called XPRESS, field data can be calculated, concatenated, and logically evaluated.
Data that is coming into the system

Forms can be the interface from web pages as well as from noninteractive systems such as ActiveSync resources. In this role, the form has no visual fields, but still provides rules to set default values and other field values.

For example, the Full Name field might not be visible to the administrator using the page, but can be set based on the values that the user enters into the First Name, Middle Name, and Last Name fields. Populating fields from other fields reduces the data entry that users and administrators must perform, consequently reducing potential data entry errors. Likewise, by providing option menus in the place of text input fields, an administrator can select a department from a list instead of entering the department name. For information on the specific HTML components that define the default Identity Manager forms, see Chapter 7, HTML Display Components.
Identity Manager background processing

Forms are also used within Identity Manager in the background processing. For example, forms can work in conjunction with resource adapters to process information from an external resource before storing it in the Identity Manager repository.

When creating forms to manipulate data in the background, you focus primarily on encoding logic because the appearance is irrelevant in forms that are not visible to users. For more information on using hidden (nonvisible) components, see the section titled Using Hidden Components.

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’/>
   </Display>
</Field>
<Field name=’global.firstname’>
   <Display class=’Text’>
      <Property name=’title’ value=’First Name’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’128’/>
   </Display>
</Field>
<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’/>
   </Display>
</Field>
<Field name=’global.fullname’>
   <Display class=’Text’>
      <Property name=’title’ value=’FullName’/>
      <Property name=’size’ value=’32’/>
      <Property name=’maxLength’ value=’32’/>
   </Display>
      <Expansion>
         <concat>
            <ref>global.firstname</ref>
            <s> </s>
            <ref>global.lastname</ref>
         </concat>
      </Expansion>
</Field>

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:

Preserve privacy by limiting the amount of user account information displayed on the screen. You may not want to present all of the information available for a user account depending on who is viewing the information because of concerns for privacy or to reduce the distraction from nonessential information.
Provide context-specific help on individual fields. This can reduce confusion and calls into your help desk.
Reduce the distraction of nonessential information for users performing a specific task. Typically, the most effective way to present information is to display only the fields you need to accomplish the current task.

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:

Address the specific needs of the users in your organization. This is particularly important when several different types of administrators must access different portions of the same view data and should not view all data attributes. For example, a human resources administrator may need to access a different subset of user account attributes than a help desk administrator.
Control the display and content of the user account attributes, particularly attributes displayed on the Create User and Edit User pages. These pages contain most of the attributes that need to be controlled.
Define default values for user view attributes and their associated attributes. For example, you could define a default home directory for a user instead of the administrator having to key in the path.
Pre-process user view attributes before they are displayed. For example, department or division codes that are stored as acronyms or by numeric ID in your resource can be represented with more human-readable full names to your user.
Post-process user view attributes data entry. For example, you can automatically create a mail account based on the value of a location field.
Control screen real estate by positioning multiple fields on one line. By customizing the arrangement of fields in an Identity Manager form, you can make it more closely resemble a printed form or pre-existing web form.
Define rules for the way hidden attributes are calculated. For example, a user’s email address can be calculated to be the user’s first name, a period, their last name, then the mail domain: joe.user@sun.com

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:

Forms that drive the graphical user interfaces. These forms, which can be part of either the Identity Manager Administrator or Identity Manager User Interface, include the pages that users use when:
- Changing passwords
- Performing self-service
- Administrative tasks that involve account creation, system configuration, and workflow tasks.
  
  You can use the default forms that ship with Identity Manager as springboards for creating your own custom forms. While you will probably want to copy and directly edit only a subset of these forms (see the section titled Edited Forms), you can peruse other forms for examples of how to encode particular attributes or behaviors.
Forms that perform background-processing on information being imported into Identity Manager from an external resource. For example, as part of the process of reading information from a PeopleSoft database into Identity Manager, a form checks employee status on incoming records. If the employee status is not active (A), the form defines a field that disables the Identity Manager account for that user.

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	`account/modify.jsp`	Tabbed User Form
Change User Account Attributes	`user/changeAll.jsp`	End User Form
Welcome	`user/anonmmain.jsp`	Anonymous User Menu
Edit Work Item	`approval/itemEdit.jsp`	Approval Form

Edited Forms

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

End User Menu Form
Anonymous User Menu Form
Tabbed User Form
End User Form
Approval Form
Change Password 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:

accounts[*].*
waveset.*
accountInfo.*
:display.session (session for admin)

Does not apply to approval pages.

Change Password Forms

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

End User Change Password – This form is the default password change form. It presents a simple set of fields with which the user can change their password. The password policies for all resources that are assigned to the user are aggregated and summarized, and Identity Manager applies the password change to all assigned resources.
Basic Change Password – This form is present in both the Administrator and User Interfaces. It provides information about the resources that are assigned to the user and allows the user to individually select on which resources Identity Manager will change the password.

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’>
<Extension>
   <List>
      <List>
         <String>End-User Test Process</String>
         <String>An example end-user workflow</String>
      </List>
   </List>

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.

<Properties>
   <Property name=’doNotRegenerateEndUserMenu’>
      <Boolean>true</Boolean>
   </Property>
</Properties>

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:

Restrict the number of attributes that are displayed on the Edit User page. By default, this page displays every attribute that is defined on the schema map for a resource, which can result in an overwhelming list of attributes for a hiring manager to fill out.
Set the default field types to more helpful select boxes, checkboxes, and multi value fields. By default, every attribute defined on a resource assigned to a user will appear on the Create User and Edit User pages as a text box (or as a checkbox for Boolean values).
Include additional forms to allow common forms to be used on multiple pages.

Tabbed User Form contains these fields:

accountId
firstname
lastname
role
organization
password
confirm password
email
resource list
application list
MissingFields

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:

Add and remove information about a user.
Assign the approver the ability to edit this information so that he can modify the information entered on the initial user form.
Create your own approval forms for different purposes. For example, you can create different approval forms for use when an administrator or resource owner initiates account creation or deletes a user.

How Do Forms Work?

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

View associated with the form. All forms are used with views. The most common view used with forms is the user view. The view defines the data that is available when the form is evaluated.
Undefined attributes. The Tabbed User Form provides a mechanism for automatically generating text fields to edit resource account attributes for which fields are not explicitly defined. You can disable this feature in the form.
How forms interact with other Identity Manager components. This includes the process by which Identity Manager evaluates the form, or form evaluation. All form-driven pages are processed similarly. For an overview of how Identity Manager evaluates a form, see Form Evaluation in this chapter.
Display components used in the form. Form fields can be associated with a display component that determines how the field is displayed in the browser.

User View and Forms

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

Attributes stored in the Identity Manager repository
Attributes fetched from resource accounts
Information derived from other sources such as resources, roles, and organizations

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:

A page is requested from the Identity Manager User or Administrator Interface.
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.
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.
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.
Default expressions are evaluated. These fields are set to the default value if the field is null.
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.
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.
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.
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.
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.
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.
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).
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.
Expansion expressions are evaluated one last time (see step 9).
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’>
   <Extension>
      <Form name=’Empty Form’>
      </Form>
   </Extension>
   <MemberObjectGroups>
      <ObjectRef type=’ObjectGroup’ name=’Top’/>
   </MemberObjectGroups>
</Configuration>

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

Checking out a view with minimal side effects.
Synchronizing data from Active Sync resources and during Load from File. Deployers typically create a customized input form for data synchronization. Identity Manager performs all attribute translations in that input form, and no further form processing is needed. However, because the operation requires an administrative context, and all administrators must use a form, you should assign the administrator’s form to an empty form to prevent further, unnecessary form processing being done on the target view.
Implementing a custom workflow that performs a particular action against a User view but which must avoid any other unforeseen side effects. In those custom workflows, it is common to specify an empty form during the checkout view process.

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.