Editing a Form

You can edit a form to change its display characteristics or add logical
processing to select fields or components. This section divides form-related
editing tasks into these two categories:

Working with display elements.
This section discusses changing the display characteristics of basic page
components when editing an Identity Manager form, especially one that is visible
to users. These components include buttons, radio buttons, and checkboxes.

Working with hidden components.
These components are the HTML elements you add to Identity Manager forms that
are used for background processing or for adding logical processing to visible
forms. These elements include the <Disable> and <Expansion> components and the FormUtil methods.

To position the button in a button row, include the following code in
your button definition: <Property name=’location ’
value=’ button ’/>. If you do not set this Property field, the button will appear in the form in the order in which
you include it in the form.

Assigning or Changing a Button Label

When defining a button, its label is identified by the value setting
in the label property as indicated below.

<Display class=’Button’>
<Property name=’label’ value=’Cancel’/>

The browser displays the preceding code as a button labeled Cancel.

Overwriting Default Button Names

Two buttons typically are displayed at the bottom of Identity Manager forms.
By default, the buttons are labeled Save and Cancel.

To Change Default Button Names

On the line that defines the form name (in the header), change
the name field

Command Values and Buttons

Note –

This section is important only if you are building Button objects.
If you are building components from XML forms, you can assume that the values
in the following table are recognized.

All pages in the Identity Manager interfaces have used the post data
parameter named command as a mechanism to convey
which form submission button was pressed. Page processing systems using components
are not required to follow the same convention, but there are some components
that contain special support for the command parameter,
in particular the Button component.

Some page processing systems, notably the one that processes XML forms,
expect the command parameter to be used. Further,
several command parameter values have been used to indicate particular actions.
These values are described in the following table.

Table 2–11 Possible Values for the
command Parameter

Parameter

Description

Save

Indicates that the contents of the form should be saved.

Cancel

Indicates that contents of the form should be thrown away.

Recalculate

Indicates that the form should be refreshed based on entered data.

Any value can be used for the command parameter,
but you must know which unrecognized command value usually results in a redisplay
of the page.

Text Fields

You can include both single-line and multi-line text entry boxes in
a form. To create a single-line text entry field, use the <Text> element.
To create a multi-line text entry field, use the <TextArea> element.

Assigning or Changing a Field Label

When defining a text field or area, its label is identified by the value property of the label property as indicated
below.

<Display class=’Text’>
<Property name=’label’ value=’Input’/>

The browser displays the preceding code as a text entry field labeled Input.

Containers

Some display elements are contained within components called container
components. Container components offer a way to:

Collect multiple components to visually organize in a particular
way. Simple containers can concatenate the components horizontally or vertically.
Other containers allow more flexible positioning of components and can add
ornamentation around the components.

Group components that you want to hide or disable on a form.

Creating a container class typically results in the generation of an HTML table tag.

Typical container components are described in the following table.

Table 2–12 Typical Container Components

Component

Description

<SimpleTable>

Arranges components in a grid with an optional row of column titles
at the top

<ButtonRow>

Arranges button in a horizontal row. This component is essentially a
panel that is preconfigured for horizontal layout.

<BorderedPanel>

Positions components into five regions: north, south, east, and west

<SortingTable>

Displays a blue and beige table with sortable columns.

Creating a Simple Table

The <SimpleTable> component is a frequently used
container component in Identity Manager forms. It arranges components in a
grid with an optional row of column titles at the top. The only property for
this display component is columns, which assigns column titles and defines
the width of the table as defined in a list of strings.

In the following example, a field that uses SimpleTable to
organize several subfields:

Working with Lists

The component you use to create a list depends upon list length and
whether the user can select more than one option simultaneously.

Text boxes often supply a list of options from which a user can select.
These lists are populated by specifying choices within a property called allowedValues or by obtaining values dynamically through a method
call (FormUtil class methods) to the resource. For information on populating
text areas with lists, see the section titled Populating Lists in this chapter.

The following table describes typical list types and the HTML display
components used to create them.

Table 2–13 Typical List Types and
Associated Display Components

Type of List

HTML Component

Option list that offers mutually exclusive values such as true and false

Creating a Checkbox

Use the <Checkbox> component to display a checkbox.
When selected, the box represents a value of true. ACreating a CheckboxCreating a Checkbox cleared
box represents a false value. You can change the checkbox name by editing
the value of the label property.

Example 2

Creating a Radio Button

Use the <Radio> component to display a horizontal
list of one or more radio buttons. A user can select only one radio button
at a time. If the component value is null or does not match any of the allowed
values, no button is selected.

Creating a Single-Selection List

Along with the <MultiSelect> component, the <Select> component provides a list of items to select from. With
longer lists of values to select from, the radio buttons can begin to take
up precious space on a form. Alternatively, select lists
can provide a way for the user to select from a long list of possible values.
This list supports type-ahead if the list is ordered. You can use the allowedValues property to specify the choices from which the user can pick.

Creating a Multiselection List

The <MultiSelect> component displays a multiselection
list box. This textbox displays as a two-part object in which a defined set
of values in one box can be moved to a selected box. Values for the list box
can be supplied by allowedValues elements or obtained dynamically
through a method call, such as getResources.

Along with the <Select> component, the <MultiSelect> component can dynamically provide a list of items from which to
select. These lists are populated by specifying choices within a property
called allowedValues or by obtaining values dynamically
through a method call to the resource. For information on populating lists
within a multiselection entry box, see the section titled Populating Lists.

Alternative Display Values in a Select List

You can create a Select list that displays a different
set of values than the values that will actually be assigned to the field.
This is often used to provide more recognizable names for cryptic values,
or to perform internationalization. This is accomplished by using the valueMap property to associate the displayed value with the actual value,
as shown in the following example:

In the preceding example, the value map is specified as a list of pairs
of strings. The odd-numbered strings are the actual values that are assigned
to this field. The even-numbered strings are the values that are displayed
in the select list. For example, if the select list entry Ted’s
Organization is selected, the value of this field becomes Top:Orgb.

Populating Lists

Lists are frequently populated with options that are dynamically calculated
from information that resides in the user object or an external resource.
When creating this type of list, you must first create the HTML list components
in the form before populating the list. (For additional information on using
the HTML text box components, see the sections titled Creating a Single-Selection List and Creating a Multiselection List.)

There are two ways to populate these lists, including the methods covered
in this section:

Populating lists with the allowedValues property

Using FormUtil methods to populate either
single-selection or multiselection lists with information dynamically derived
from an external resource.

Populating Lists of Allowed Values

The most typical way of populating lists in forms is through the use
of the allowedValues property. From this property, you
can specify an optional list of permitted values for <Select> and <MultiSelect> elements. The value of this component is always
a list and usually contains strings.

Dynamically Populating a Multiselection List of Groups

Multiselection lists typically contain two parts:

The left side of the list displays the items that are available
for selection. These values are defined by the allowedValues property.
This property can be a list of strings, a list of XML object strings, or a
list of strings returned from a call to a Java method.

The right side of the list displays the items that are currently
selected. These values are set by selecting one or more items from the left
side’s allowedValues list and pushing these selections
to the selected list. The right side of the list is also populated when the
form is loaded and the current settings are retrieved.

Adding a Multiselection List of Groups

To add a multiselection list of groups that is populated dynamically
from the resource

Add groups to the right side of the schema map. The values
displayed in the right side of a text area that displays a multiselection
list are populated from the current value of the associated view attribute,
which you identify through the field name.

Add the following text to any form, changing only the Field
name, prompt, availabletitle, selectedtitle, and the name of the resource as
needed.

Note –

In the following example, the: (colon) that precedes display.session indicates that you can ignore the base context of the form and
reference objects from the root of the workflow context.

In the following example, the : (colon) that precedes display.session indicates that you can ignore the base context of
the form and reference objects from the root of the workflow context.

<Field name=’global.AD Groups’>
<Display class=’MultiSelect’ action=’true’>
<Property name=’title’ value=’AD Group Membership’/>
<Property name=’availableTitle’ value=’Available AD Groups’/>
<Property name=’selectedTitle’ value=’Selected AD Groups’/>
<Property name=’allowedValues’>
<invoke class=’com.waveset.ui.FormUtil’ name=’listResourceObjects’>
<!-- send session information which will be used by the method to
validate authorization user -->
<ref>:display.session</ref>
<!-- resource object type– This will differ from resource to
resource, but common types are account, group, and
“distribution list” -->
<s>Group</s>
<!—- Name of resource being called -->
<s>AD Resource Name</s>
<!-- options map– Some resources have options like the context
that the group is listed in.For example, active directory has multiple
containers. By default, the container used will be the one specified on
the resource.The value can be overridden by specifying it here.
If the resource does not support options,the value should be <null/> -->
<Map>
<MapEntry key=’context’ value=’ou=Austin,ou=Texas,dc=Sun,dc=com’/>
</Map>
<!-- cacheList– specify true or false whether you would like this list to
appear in the Resource Object List Cache-->
<s>true</s>
</invoke>
</Property>
</Display>
</Field>

Note –

If the resource does not support options, the value of options
map should be null. Some resources have options such as the context that the
group is listed in. For example, Active Directory has multiple containers.
By default, the container used will be the one specified on the resource.
This value can be overridden by specifying it here.

Specify the
value of cacheList as true or false to designate whether this list should
be stored in the Resource Object List Cache. This will cause the method to
be run once, and the results are stored on the server.

Creating a Text Entry Field in a Selection List

There are some conditions under which you’d like to include an
option in a selection list in which the user can enter a value instead of
choosing from the list. You can create this feature by implementing the three
fields as shown in the following example.

This example creates a selection box with the text string Other in it and an adjacent text box. When the user selects the
Other option from the selection box, the page presents a new field in which
the user can enter custom information.

Implements the defvar element to create a variable that defines
a list of job positions from which a user can select a relevant position.

Note –

Consider putting into a rule any variables that will be referenced
in a form multiple times. In the following example, a list of items to select
from is stored in a variable (in the example, titleList),
which allows the Derivation rule to search through it.

The next part of this example contains two visible fields called title and otherTitle. The otherTitle field
is displayed only if the user chooses the other option on the selection list.
The third hidden field is global.Title, which is set from
either Title or otherTitle.

The Title field is the main field that the user will
select from. If the user cannot find the item that he wants in the list, he
can select Other. This is a transient field and is not
stored or passed to the workflow process when you click Save. A Derivation
rule is used to send the value from the resource and determine if the value
is in the list.

Note –

In the following example, action is set to
true to ensure that form fields populate automatically.

The Other field will appear on the form only if the
user has selected Other from the title field. The value of the Other field
is set when the form is loaded. It is based upon the value of the Title field
and the global.title field.

The value of Field is based on the value of the Title field. If the
value of this field is set to Other, then the field value is defined by the
value of the otherTitle field. Otherwise, it will be the value of the Title
field.

Filtering the List of Resource Accounts before Display
in a Form

You can filter the list of resource accounts before displaying them
in a form. By default, no filters are applied, except with the Change Password
Form in the User Interface, which preserves the default behavior of filtering
disabled accounts from the list displayed to the user.

This Exclude filter is defined as a Form property. The filter is a list
of one or more AttributeConditions that, when evaluated, determine if a given
resource account should be excluded from the displayed list.

Forms that Support This Feature

The following Forms support the specification of an Exclude filter as
a Form property:

Calling a FormUtil Method from within the allowedValues
Property

From within the allowedValues property, you can also
call FormUtil methods
that permit you to dynamically retrieve and process information from a resource
external to Identity Manager, such as a database.

This example shows how to call a FormUtil method to populate a <Select> list. In the following example, the method is called from within
the allowedValues property. The getOrganizationsWithPrefixes method (or any FormUtil method) is invoked from within an expression.

XPRESS also supports the ability to invoke calls to Java methods from
within a resource or ActiveSync adapter. The results of the calls can then
be used to populate multiselection or select lists. For information on invoking
methods from an expression, see Chapter 5, XPRESS Language

Creating a Label Field

Labels are useful components for displaying the value of a read-only
field. Properties of the <Label> component permit you
to define the display characteristics of the label, including color, value
(string), and font style.

Working with Other Display Elements

Other display elements that you might want to incorporate into a form
include:

section header

calendar icon

back link

Adding a Section Heading to a Form

Section heads are useful to separate sections of long forms with a prominent
label. The <SectionHead> element displays a new section
heading defined by the value of the title (prompt) property.
It is an extension of the Label class that sets the font
property to a style that results in large bold text. It also sets the pad property to zero to eliminate the default two-space padding.

Adding a Calendar Icon to a Form

You can add a calendar icon to a page with the DatePicker element. The
user can click this icon to select a calendar date and populate a page field.
For example, the Identity Manager Create Audit Report page uses this component
to select start and end dates.

The DatePicker element returns a date object. Most resource attributes
that you set using DatePicker require a date in the form of a string. The
extra text field performs the conversion of the new date object into a string
or displays the current setting.

You can obtain the date in one of several formats by passing a different
format string to the invoke dateToString method as indicated
in the following table.

The field defined below displays the password expiration date as found
in the /etc/security/user file. It also displays any new
date selected by the aix_account_expire field if the refresh
or recalculate is performed after selecting a new date. Identity Manager looks
to see if the aix_account_expire date field has been set
(not null) from the DatePicker field.

If this date field has been set, Identity Manager calls an invoke method
to convert the date object into a string in the specified format: MMddHHmmyy.

Otherwise, display the current date as set on the AIX OS: accounts[AIX].aix_expires.

Positioning Components on a Form

The location of a component on a form is determined by the following
factors:

The Java Service Page (JSP) associated
with this form. The title and subtitle of the form can be set here.

Order in which the components are
listed in the form. The browser will display form fields in the
order in which they are included in the form.

Use of container forms.
For example, to create a vertical row of buttons, use the <ButtonRow> container component.

Using Hidden Components

Many forms are not visible to the user but help process data from an
external resource through the resource adapter before passing it into Identity Manager.
In visible forms, too, some components can be hidden. These hidden components
are used to process this incoming data as well as to transform data in visible
forms.

Some hidden processing within forms is carried out by the methods in
the FormUtil Java class. These are frequently used when populating lists in
forms from information retrieved dynamically from an external resource.

This section discusses the following tasks, which permit you to process
data and optionally hide this processing in forms. Typical tasks include:

Adding a Password Confirmation Challenge

Including XPRESS Logic Using Derivation and Expansion elements

Calling Methods to Populate Lists

Building DN strings

Getting a list of object types for which the session owner
has access

Getting a list of organizations

Getting a list of unassigned resources

Obtaining a list of resource object names

Disabling components

Hiding components

Adding a Password Confirmation Challenge

You can add a password confirmation challenge to select forms by adding
a RequiresChallenge property. When this feature is enabled,
Identity Manager will challenge the currently logged-in administrator for
his password before processing a request. The forms that support this option
include:

userForm (Tabbed User form, Wizard User form, and default
User form)

changePassword (by default, Change Password form)

reset PasswordForm (by default, Reset User Password form)

You specify this property differently for each form.

Setting the RequiresChallenge Property for User Forms

To add a password confirmation challenge to a user form, add the following
RequiredElement element as shown below, with substitutions for password, email,
and fullname:

The value of the property is a list of one or more of the following
User view attribute names: applications, adminRoles, assignedLhPolicy, capabilities, controlledOrganizations, email, firstname, fullname, lastname, organization, password, resources, roles.

To add a password confirmation challenge to either changePassword or
resetPassword form, add the following <RequiresChallenge> element
as shown below, with substitutions for password, email, and fullname:

<Property name='RequiresChallenge' value='true'/>

where the value of property can be either true or false.

If the property is set to true in the form, Identity Manager will challenge
the current administrator who is requesting the change to enter the password
he used to log in to Identity Manager. If the challenge is not successful (that
is, the current administrator's password is not entered), Identity Manager will
not permit the challenge. If the challenge is successful, Identity Manager will
permit the change request to proceed. Both password management forms support
the use of the RequiresChallenge form property. When this
property is set to true, the user is prompted to enter the old password after
specifying the new password.

Including XPRESS Logic Using the Derivation and Expansion
Elements

Typically, a field will have either a Derivation rule
or an Expansion rule. If a field includes both types of
rules, make sure that these fields do not conflict with each other.

You implement the <Expansion> and <Derivation> components to use XPRESS to calculate values for form fields. These
expressions are similar, differing only in the time at which the expression
is evaluated. Derivation rules are typically used to set the value of the
field when the form is loaded. Expansion rules are used to set the value of
the field whenever the page is recalculated or the form is saved.

Table 2–15 Derivation and Expansion
Expressions

Component

Description

Evaluation

<Derivation>

Unconditionally calculates an arbitrary value to be used as the value
of this field. Whenever a Derivation expression is evaluated, the current
field value is replaced.

Derivation rules are run when the form is first loaded or data is fetched
from one or more resources.

<Expansion>

Unconditionally calculates a value for the field

Expansion rules are run whenever the page is recalculated or the form
is saved.

For all forms except the User view, Expansion rules are run whenever
the page is recalculated or the form is saved. For the User view, an <Expansion> tag runs when the user form is first loaded as well.

<Validation>

Determines whether a value entered in a form is valid.

Validation rules are evaluated whenever the form is submitted.

Examples of <Derivation> Statements

The following two examples illustrate the potential use for the Derivation

Example 1: Specifying an authoritative source for a global
field

Example 2: Mapping one set of values into another set

Example 1:

The following example uses the first value, if defined. If the first
value is not defined, then it uses the second value.

The following example of using the <Derivation> element
shows a field definition that uses conditional logic to
map one set of values into another set.

In this example, the resource account attribute accounts[Oracle].locCode is evaluated against the AUS case element first. If it is true,
then the second value is the value returned and displayed in the location field. If no cases are matched, then the value of the default case
is returned. When a matching abbreviation is found as the first expression
within a case expression, the value of the second expression within the case
expression is returned as the result of the switch expression.

Examples of <Expansion> Statement

The following two examples illustrate the potential use for the Expansion element.

Example 1: Implementing a rule to standardize the case of
text entered in a field

Example 2: Hiding expansion logic

Example 1:

Expansion rules transform information that has been entered into a field
into values that match the format expected by the resource or established
by a rule. For example, a free-form text box in which a user enters a name
can include an Expansion rule that capitalizes the first
initial and lowercases the others.

The use of the global attribute in fields sets any of the resources
that have this value when the form is saved. When you load this form, Identity Manager loads
the values from each resource (unless the field is disabled). The last resource
load sets the value in the form. If a user has made a local change, this change
may not show up. Consequently, to ensure that the correct value for the attribute
is used, you can use a Derivation rule to specify one or
more of the resources as an authoritative source for the field.

As the preceding XPRESS logic could be implemented in multiple fields,
consider presenting it in a rule.

Example 2:

In the following example, this field is also hidden by the absence of
any Display class definition. The lack of Display class
definition prevents the field from being displayed in the form, but the field
is still considered to be an active part of the form and will generate values
for resource attributes through its <Expansion> expression.

In this example, it performs the reverse of the mapping performed by
the location field.

Example of <Validation> Statement

Validation expressions allow you to specify logic to determine whether
a value entered in a form is valid.

The validation expression returns null to indicate success, or a string
containing a readable error message to indicate failure. The system displays
the validation error message in red text at the top of the form.

The following example contains the logic to determine whether the age
entered by user in a field is greater than 0. This expression returns null
if the age is greater than or equal to zero.

Calling Methods to Populate Lists

Lists in single-selection and multiselection text boxes are often populated
with choices that are derived from information from external resources. You
can populate lists dynamically with this information by calling one of the
FormUtil methods supplied by Sun. These common methods can perform the following
tasks:

Obtain a list of resource object names

Obtain a List of Resource Objects without Map Options

Build DN strings

Retrieve a list of accessible object types

Retrieve a list of object types accessible by the session
owner

Get a list of organizations with prefixes

Get a list of organizations without prefixes

Get a list of organizations display names with prefixes

Retrieve a list of applications unassigned to the user

For information on the <Select> and <MultiSelect> components and the allowedValues property, see
the section titled Populating Lists.

Understanding Resource Object Names

To search for or request information on a resource and import it into Identity Manager,
you must use object definitions supported by Identity Manager.

The following table lists the object types supported by Identity Manager.

Table 2–16 Supported Resource Object
Types

Supported Object Types

Description

account

List of user accounts IDs

Administrator_Groups

Names of the administrative groups to which a user can belong

Applications

List of applications

Distribution Lists

List of email distribution aliases

Entitlements

List of PKI entitlements

group

List of security and distribution list group objects

Group

Security groups

Nodes

List of SP2 nodes

PostOffices

List of GroupWise post offices

profile

List of top secret profiles

PROFILE

List of Oracle profiles from the DBA_PROFILES table

ROLE

List of Oracle roles from the DBA_ROLES table

shell

List of available UNIX shells

Template

List of NDS Templates

USERS

List of Oracle profiles from the DBA_USERS table

UnassignedTokens

List of available unassigned tokens

User_Properties

List of user property definitions

Obtaining a List of Resource Object Names

To obtain a list of object names defined for your particular resource,
use the listResourceObjects method. You can obtain a list
with or without map options. Map options are used only on resources that have
a directory structure that permit the filtering of returned values to a single
container instead of returning the complete list.

To ensure that you get the resource object list from the resource and
not from the server’s cache, first invoke the clearResourceObjectListCache() method or set the cacheList argument
to false. However, using the cache improves performance on large lists. The
resource is contacted only once, and the results are stored on the cache.
Consequently, Sun recommends using the cache.

In addition, you can specify a set of one or more key/string value pairs
that are specific to the resource from which the object list is being requested.

The following table lists the object types that are supported by each
resource.

You can specify any Active Directory valid object class name as an object
type. (A list of object class names can be found in the Active Directory schema
documentation.) The list returned contains the distinguished names of the
objects. By default, the method searches in the container that is specified
by the Container resource attribute. However, you can specify a container
as an option to the listResourceObjects call. Its value
should be the distinguished name of a container. Only objects within that
container are listed.

Obtaining a List of Resource Objects without Map
Options

To obtain a list of resource objects without map options, specify the
resource object type and resource name. Note: Some resources support acting
on a subset of a list. You can do this by specifying a starting directory.

In the following example:

The <UnassignedTokens> string identifies
the resource object type that you want to get. Other common resource object
types are groups, distribution lists, and accounts.

The <SecurID> string identifies the
resource from which the object type is retrieved.

Obtaining a List of Resource Objects with Map Options

To obtain a list of resource objects with map options, specify the resource
object type, resource name, and a map option that defines the directory to
start the search in. The resource must be directory-based.

For example, you can get a list of all Active Directory groups in the
Software Access directory by building a map option that performs the search
in the directory path (ou=Software Access, dc=mydomain, dc=com).

Example:

In the following example

The Group string identifies the resource
object type that you want to get. Strings that identify resource object types
are identified in the table titled Available Resource Object Types.

The AD string identifies the resource name
from which to retrieve the object type. Map options specify the directory
from which to retrieve the list.

Building DN Strings

With a given user ID and base context, you can dynamically build a list
of distinguished names or a single distinguished name. This method does not
return a list and is typically used within an Expansion rule.

Building a Dynamic List of DN strings

You can dynamically build a list of DN strings if you specify a user
ID and base context.

The following example shows how to use user IDs and base context to
build a dynamic list of DN strings.

Disabling Fields

When you disable a field, the field (and any fields nested within it)
is not displayed in the page, and its value expressions are not evaluated.
If the view already contains a value for the disabled field, the value will
not be modified.

<Disable></Disable>

Note –

Keep in mind that global.* attributes are derived
from enabled fields only. If a form dynamically disables a field (instead
of hiding it), this field value will not be available through the global.* attributes.

Example:

<Disable>
<eq><ref>userExists</ref><s>true</s></eq>
</Disable>

Note –

Disable expressions are evaluated more frequently than other types
of expression. For this reason, keep any Disable expression relatively simple.
Do not call a Java class that performs an expensive computation, such as a
database lookup.

Hiding Fields

When you hide a field, the field (and any fields nested within it) is
not displayed on the page, but its value is included in the form processing.

To hide a field, specify that a particular field is hidden by not defining
a Display property for the field. (This is not conditional.)

<Field name=’field A’/>

Calculating Values

Methods for dynamically calculating values within forms include:

Generating field values

Including rules in forms

Including XPRESS statements in a form

Generating Field Values

In some forms, you might want to first display a set of abstract derived
fields to the user, then generate a different set of concrete resource account
attribute values when the form is submitted. This is known as form
expansion. Expanded fields are often used in conjunction with derived
fields.

Including Rules in Forms

In forms, you typically call a rule to calculate the allowedValues display property or within a <Disable> expression
to control field visibility. Within forms, rules could be the most efficient
mechanism for storage and reuse of:

Including XPRESS Statements

The XPRESS language is an XML-based expression and scripting language.
Statements written in this language, called expressions,
are used throughout Identity Manager to add data transformation capabilities
to forms and to incorporate state transition logic within Identity Manager objects
such as Workflow and forms.

XPRESS is a functional language that uses syntax
based on XML. Every statement in the language is a function call that takes
zero or more arguments and returns a value. Built-in functions are provided,
and you can also define new functions. XPRESS also supports the invocation
of methods on any Java class and the evaluation of Javascript within an expression.

Why Use XPRESS?

Expressions are used primarily for the following Identity Manager tasks:

Customizing the end-user and administrator
forms. Forms use XPRESS to control the visibility of fields and
to transform the data to be displayed and saved.

Defining flow of control in Workflow.
Workflow uses XPRESS to define transition conditions,
which determine the order in which steps in the workflow process are performed.

Implementing workflow actions.
Workflow actions can be implemented using XPRESS. Action expressions can perform
simple calculations, or call out to Java classes or JavaScript to perform
a complex operation.

The expressions contained in these elements can be used throughout Identity Manager.

Example Expression

In the following example, the <add> element represents
a call to the XPRESS function named add.

<add> <ref>counter</ref> <i>10</i> </add>

This function is passed two arguments:

first argument– value is
determined by calling a function named ref. The argument
to the ref function is a literal string that is assumed
to be the name of a variable. The value returned by the ref function
is the current value of the variable counter.

second argument -- value is determined
by calling a function named i. The argument to the i function
is a literal string that is an integer. The value that the i function
returns is the integer 10.

The value returned by the add function will then
be the result of adding the integer 10 to the current value of the variable counter. Every function call returns a value for the next operation
to use. For example, if the ref call returns the value
of the counter, then the <i> call returns the integer
10, then the <add> call returns the addition of the
two calls.

Example of Expression Embedded within Form

The following example shows the use of XPRESS logic embedded within
an Identity Manager form. XPRESS is used to invoke one of the FormUtil Java
methods that will produce the relevant role-related choices for display in
the browser. Note that the expression is surrounded by the <expression> tag.

Edit User Form

Identity Manager can identify in the display whether an attribute in
a resource’s schema map is required. Edit User form identifies these
attributes by a * (asterisk). By default, Identity Manager displays this asterisk
after the text field that follows the attribute name.

To customize the placement of the asterisk, follow these steps:

To Customize the Resource Schema Map

Using the Identity Manager IDE or your XML editor of choice, open
the Component Properties configuration object.

Add EditForm.defaultRequiredAnnotationLocation=left to
the <SimpleProperties> tag.

Valid values
for defaultRequiredAnnotationLocation include left, right, and none.

Save your changes, and restart your application server.

Adding Guidance Help to Your Form

Identity Manager supplies two types of online help:

Help, which is task-related help and information available
from a button in the Identity Manager masthead. You cannot configure this help.

Guidance (pop-up help), which is field-level help that is
available left of the field or area that is marked with a guidance icon .

How to Specify Guidance Help for a Component

You can associate guidance help text with any component, although it
is currently displayed only by the EditForm container.
You can specify guidance text by associating it with the component by matching
the component’s title property with an entry in a
help catalog. See the section titled Matching the Component’s title Property with a Help Entry.

Matching the Component’s title Property with
a Help Entry

You can automatically associate help catalog entries with components
by using key values in the catalog that are the same as component titles appended
with the suffix _HELP. For example, the help catalog entry for the _FM_DELEGATEWORKITEMSFORM_SELECT_WORKITEM_TYPE
key is _FM_DELEGATEWORKITEMSFORM_SELECT_WORKITEM_TYPE_HELP. When using XML
forms, a component title can be specified explicitly with a Property element.
Otherwise, it will be taken from the value of the prompt attribute
of the containing Field element.

Overriding Guidance Help

You can use a custom message catalog to override the guidance text that
displays in a pop-up window. If you name your custom message catalog defaultCustomCatalog, Identity Manager recognizes
and uses it automatically. Alternatively, you can choose a different name,
and then specify that name in System Configuration object under the customMessageCatalog
name

Overriding Version Information

You can create two custom message catalog keys that prevent Identity Manager from
displaying the version information when a user places the cursor over the
help button. The UI_END_USER_VERSION key hides the version information on
the end user interface, while the UI_VERSION key is used by the administrator
interface.

Setting the value of the key to the empty string prevents any version
information from being displayed.

The following example disables version information for both interfaces.

Other Form-Related Tasks

Invoking the FormUtil Methods

The FormUtil
class is a collection of utility methods that you can call from XPRESS expressions
with form objects. They can be used to populate lists of allowed values and
validate input. The FormUtil methods are typically called to assist the definition
of the allowed values in a list or field.

Inserting JavaScript into a Form

To insert pre-formatted Javascript into a form, use the <script> component as follows:

<Field>
<Expansion>
<script>
............

Testing if an Object or User Exists

You might want to check whether an object exists before performing an
action. For example, you could look to see if a user name exists in Identity Manager before
creating a new user, or validate whether a manager name entered in a field
is valid.

To test if an object exists, use the testObject method.
To specify an object type when using this method, use the object types listed
in the section titled Retrieving a List of Accessible Object Types. In the following example, the user type is identified
as <s>User</s>. The second string gives the value
of the object type (in this example, jdoe).

Wizard and Tabbed Forms

Both wizard and tabbed forms are mechanisms for structuring unwieldy,
single-page forms into more easily managed, multiple-paned forms. Both contain
separators between logical sections, or pages. These page separators can be
tabs located at the top of the form -- like the tabbed user form -- or a wizard
form, which guide the user through the pages using the next/back navigation
buttons.

See Tabbed User Form in this chapter
for the XML version of the default Tabbed User Form.

What Is a Wizard Form?

Wizard forms can be a convenient alternative to launching multiple forms
from a task when:

Transition logic between pages is simple

Privileged system calls between pages are required

Wizard forms contain the two rows of buttons described below.

Table 2–18 First Row of Buttons

Row of buttons

Description

top row

Next and Back buttons to traverse through the form panes

second row

Contains the standard user form buttons listed in the following table.
You can control the second row by setting noDefaultButtons option
to true and implementing your own buttons.

This second row of button can vary as follows:

Table 2–19 Second Row of Buttons

Wizard page

Default buttons

first page

Next, Cancel

intermediate pages

Prev, Next, Cancel

last page

Prev, Ok, Cancel

Implementing a Wizard Form

Wizard form syntax closely resembles tabbed user form structure. ,

To Create a Wizard Form

Assign the WizardPanel display class to the
top-level container (rather than TabbedPanel).

Set the noCancel property to true.

Define one or more EditForm fields that contain the pages of the
wizard.

Tips and Workarounds

Validation errors appear on the last page that the user was
on rather than the page on which the attribute appears. To work around this,
include information in the validation message to assist the user in navigating
back to the correct page.

For complex wizards, give users some visual clue as to where
they are in the process. Using labels or section heads at the top of every
page that displays text similar to Page 1.

Avoid using conditional navigation in wizard forms. If you
must implement it, use Disable expressions for each of the immediate children
of the WizardPanel. For example:

Put fields or buttons on previous pages that cause their gating
variables to be set. Disabled pages are automatically removed from transition
logic.

Alternatives to the Default Create and Edit User
Forms

When an administrator uses the default User form to edit a user, all
resources that are owned by a user are fetched at the moment an administrator
begins editing a user account. In environments where users have accounts on
many resources, this potentially time-intensive operation can result in performance
degradation. If you are deploying Identity Manager in this type of environment,
consider using scalable forms as an alternative to the
default Create and Edit User interfaces.

Overview: Scalable Forms

Scalable forms are customized forms that help improve
the performance of Identity Manager’s Edit and Create User interfaces
in environments with many users and resources. This improved performance results
from several features, including:

Incremental Resource Fetching

Incremental resource fetching describes one method
used by the Identity Manager server to directly query a resource for information
over a network connection or by other means. Typically, when an administrator
edits a user using the default user form, all resources that are owned by
a user are fetched at the moment an administrator begins editing a user account.
In contrast, the intent behind the design of scalable forms is to limit fetching
by fetching only those resources that the administrator wants to view or modify.

Selective Browsing

Selective browsing, another feature incorporated
into scalable forms, permits an administrator to incrementally view resources
based on their owning role, on their resource type, or from a list of resources.

Multiple Resource Editing

Multiple resource editing allows an administrator
to select subsets of resources for editing resource attributes. An administrator
can select subsets based on roles, resource types, or from a list of resources.

When to Use Scalable Forms

Consider using scalable forms when

Administrators are manually editing
users who have many resource accounts. Implementing a scalable
form under these circumstances allows administrators to selectively edit specific
resource accounts without incurring the overhead of fetching the user’s
data for all resource accounts. This mechanism is particularly useful when
a certain type of resource responds much slower than the other resource types
associated with a user.

Custom provisioning processes, such as ActiveSync, target
only specific resources for updates

Note –

Do not use scalable forms when form logic includes attributes
that reference other resources. In this configuration, these cross-reference
attributes will either not be populated with the latest data, or these resources
should be fetched together.

Do not use scalable forms when form logic includes attributes that reference
other resources. In this configuration, these cross-reference attributes will
either not be populated with the latest data, or these resources should be
fetched together.

In addition, the scalable version of the Create User form provides limited
benefit over the standard default version because a new user has no resources
to begin with.

Available Scalable Forms

Identity Manager ships the following two scalable user forms, which are
described below:

Dynamic Tabbed User form, which provides an alternative to
the default Tabbed User form

Dynamic Tabbed User Form

Provides an alternative to the default Tabbed User form, which fetches
all resources as soon as an administrator begins editing. In contrast, Dynamic
Tabbed User form features incremental fetching and editing of multiple resources
based on resource type.

Note –

For detailed implementation information, see the comments associated
with each user form in WSHOME/samples/form_name.xml.

Importing and Mapping the Form

Three forms are involved in the substitution of Dynamic Tabbed User
form for the default Tabbed User form.

Table 2–20 Forms associated with Dynamic
Tabbed User Forms

Form

Description

Dynamic Tabbed User Forms

Contains the features of the default Tabbed User Form but dynamically
creates one tab per resource type.

Dynamic User Forms

Contains fields for creating resource type tabs on the user form.

Dynamic Forms Rule Library

Contains the rule library for dynamically printing out attributes for
resources that have no specified user form.

Dynamic Resource Forms

Contains all forms that are currently compatible with the Dynamic Tabbed
User form. Users can customize this list.

Installing Dynamic Tabbed User form involves two steps: importing the
form, and changing the form mapping.

Step 1: Import the Form

Enter the file name (dynamicformsinit.xml)
or click Browse to locate the dynamicformsinit.xml file in the ./sample directory.

Click Import. Identity Manager responds
with a message that indicates that the import was successful.

Step 2: Change Form Mapping

There are two methods of assigning a user form to an end user. Select
a method to edit these form mapping depending upon how administrators in your
environment will be using these forms. These methods include:

Assign Scalable User Form as the default
User Form for all administrators. If this is your choice, see Step 2: Change Form Mapping. Identity Manager administrators
can assign one form that all administrators will use.

Assign Scalable User Form as the Default User Form

From the menu bar, select Configure >
Configure Form and Process Mappings.

In the Form Mappings section, locate userForm under
the Form Type column.

Specify Dynamic Tabbed User Form in the box provided under the
Form Name Mapped To column.

Assign Scalable User Form per Administrator

From the menu bar, select Accounts > Edit
User.

Select a user in one of these two ways:

Click on user name, then click Edit

or

Right-click on the user name to display a pop-up menu, then
select the Edit menu option

After the Default Edit User Form appears, click on the Security
tab.

Find the User Form field and select Dynamic Tabbed User Form.

Click Save to save the settings.

Resource Table User Form

The Resource Table User Form contains most of the driving logic of the
scalable version of the Edit User form. This form implements incremental fetching
and multiple resource editing based on resource type.

For additional implementation information, see the comments in WSHOME/samples/resourcetableformsinit.xml.

Importing and Mapping the Form

Five forms are involved in the substitution of Resource Table User form
for the default Tabbed User form.

Table 2–21 Forms Associated with Resource
Table User Form

Form

Description

Resource Table User Form

Contains all globally available fields that are used for navigation,
incremental fetching, and form layout. This main form drives all the other
resource-related scalable forms.

Step 1: Import the Form

Enter the file name or click Browse to
locate WSHOME/sample/resourcetableforms.xml. Importing
this file also imports:

Step 2: Change Form Mapping

From the menu bar, select Configure >
Configure Form and Process Mappings.

In the Form Mappings section, locate userForm under
the Form Type column.

Specify Resource Table User Form in the box provided under the
Form Name Mapped To column.

Customizing Scalable Forms

After importing and mapping the scalable user form, you must customize
it. To enable incremental fetching, you must identify:

resources accounts that are initially
fetched. Use the TargetResources form property
to represent the resource names to be included on the fetch.

operations that are updated when
the final save operation occurs.

Both the Dynamic User Forms and the Resource Table User Forms use resource-specific
forms for displaying a user’s resource-specific attributes. The following
user forms are located in the WSHOME/sample/forms directory and have been
adapted for use by scalable forms.

./ACF2UserForm.xml

./ActivCardUserForm.xml

./ADUserForm.xml

./AIXUserForm.xml

./BlackberryUserForm.xml

./ClearTrustUserForm.xml

./HP-UXUserForm.xml

./NDSUserForm.xml

./OS400UserForm.xml

./PeopleSoftCompIntfcUserForm.xml

./RACFUserForm.xml

./SAPPortalUserForm.xml

./SolarisUserForm.xml

./SunISUserForm.xml

./TopSecretUserForm.xml

These forms are automatically imported along with both Dynamic Tabbed
User Forms and Resource Table User forms.

If a deployment is using a resource type other than a type listed above,
the scalable forms display a default User form that simply lists all attribute
name and values specified in the schema mapping. To use an existing customized
resource user form other than those listed above, you must make certain modifications
in order to ensure compatibility with the scalable forms. The following procedure
describes some of the steps necessary to ensure compatibility.

Note –

Refer to any one of the forms in this list as an example of this
modification.

Customizing a Resource Form for Compatibility with
Scalable User Forms

To add your own customized resource form for use with either the Dynamic
Tabbed or Resource Table user forms, follow these general steps.

Step One: Modify Dynamic Resource Forms

Instructions for adding your own resource form are provided in the dynamicformsinit.xml file. Search within this file for the Dynamic
Resource Form and follow the steps provide with the form.

Note –

The steps described within the form are presented in comments,
and are not displayed in the form once it is imported.

Step Two: Modify Your Resource Form

If you are not using a form from the preceding list, you will need to
modify your resource form so that it is compatible. Refer to any of the files
listed above for examples. Instructions are listed on the top of each resource
form.

To update two resources with different passwords simultaneously, you
must generate a separate password field for each assigned resource. For example,
you can have an AD password field on the AD resource Attribute area (on the
Accounts page) that still conforms to password policies that can be set separately
from other resources.

Default Password Policy Display

To move the password fields from their default position on the Identity
area to the Attribute area, you must disable the default Identity Manager password
synchronization mechanism by following these three steps:

To Move the Password Fields from Their Default Position

Set the manualPasswordSynchronization checkout
property

Add Field and FieldLoop components
to the Tabbed User form

Add resource-specific password fields to the Tabbed User form

These steps are described in more detail below.

Step One: Set the manualPasswordSynchronization Checkout
Property

Specify the manualPasswordSynchronization view check
out option by adding the following property to the form:

When manualPasswordSynchronization is set to true, Identity Manager displays
per-resource password fields rather than using the password synchronizer.

Step Two: Turn Off Password Synchronization

You can disable password synchronization by turning off the selectAll
flag under the Password view. To do this, add the following fields to the
default forms:

<Field name=’password.selectAll’>
<Comments>
Force the selectAll flag off so we do not attempt synchronization.
Necessary because it sometimes is set to true by the view handler.
</Comments>
<Expansion><s>false</s></Expansion>
</Field>
<FieldLoop for=’res’>
<expression>
<remove>
<ref>password.targets</ref>
<s>Lighthouse</s>
</remove>
</expression>
<Comments>
Also must force the individual selection flags to false and display
a password prompt for each resource since the view handler will
default to true for new accounts.
</Comments>
<Field name=’password.accounts[$(res)].selected’>
<Expansion><s>false</s></Expansion>
</Field>
</FieldLoop>

Step Three: Add Resource-Specific Password Fields
to Attributes Page

Write resource specific password fields for each resource as follows:

<Field name=’accounts[resname].password’>

Turning Off Policy Checking

You can turn off policy checking in your user form by adding the following
field to the form:

This field overrides the value in the OP_CALL_VIEW_VALIDATORS field
of modify.jsp.

Tracking User Password History

By default, Identity Manager does not track user password changes initiated
by administrators. The following options allow administrators to change this
default behavior. Choose the option that best suits your deployment.

Option 1: Adding a View Option to a Form

You can add a view option to the target form, as shown below. Note that
this view option will override any system configuration setting. Specifically,
if you set the view option to true, and the relevant system
configuration attribute is false, Identity Manager follows
the view option and ignores the system configuration setting.

If you are working with a target form that is not part of ActiveSync
processing, set the savePasswordHistory attribute on the
target form (typically User form) as shown below.

To record password changes during Active Sync configuration, you must
set the savePasswordHistory view option in a different
way. You can modify the Synchronize User Password TaskDefinition by adding
the following action to the SetPasswordView Activity.