The Identity Manager User Interface implements a second XPRESS form that
contains the navigation bar. This means that the rendered page has two <FORM> tags, each with a different name attribute:

<form name="endUserNavigation">

and

<form name="mainform">

Form Components

The following table identifies form components in the order in which
they appear in the form. Each form component is discussed in greater detail
below.

Table 2–7 Form Components

Form Component

Purpose

header

Introduces information about the form object definition. Includes start
tags for <Form>, <Extension>,
and <Configuration> elements and defines form properties
(such as title, subtitle, titleWidth displayed when the form is launched).

form body

Contains field definitions, form functions, form variables. This is
the part of the form that you will edit.

footer

Closing tags for <Form>, <Extension>,
and <Configuration> elements.

Header

The form header includes:

Standard introductory information included in XML files: the
XML declaration and documentation declaration, including the DTD associated
with this XML file. In the preceding example, this introductory information
is:

Start tags for the <Extension> and <Configuration> elements, which surrounds the HTML components
that describe the form’s appearance and behavior. The Configuration
element contains attributes that describe the form object properties.

The header contains information about the form, including internal identification
such as date of creation, login of whoever last modified the file, and the
form type. The page processor typically generates this information.

Note –

The system generates the following information for internal use
only. Do not edit these attributes.

Table 2–8 Form Header Components

Element

Definition

<Extension>

Required to wrap the <Form> element.

<Element>…</Element>

<Configuration>

Contains information that the system uses internally when processing
the form object, including the date of last modification and login of the
user who last modified this form. Most of this information is typically associated
with any persistent object that is stored in the Identity Manager repository.
You typically do not need to edit this information.

Form Body

The form body is composed of:

Form properties, which include title, subtitle, and width.
These properties are defined in the table titled Form Properties.

Field elements, which you use to determine the appearance
and function of the fields as they appear to the user in the product interface.
Fields can also contain XPRESS logic to calculate information. For more information
on using the XPRESS language, refer to XPRESS Language.

The following table lists form header properties.

Table 2–9 Form Header Properties

Property

Purpose

title

Identifies the text that appears at the top of the form. Typically,
this title is in a bold font typically larger than the other font on the screen.
The form title appears under the Identity Manager page.
You cannot edit the display characteristics of title.

In the example given in the section titled Form Components,
the value of title is User Self Service

subtitle

Identifies text that appears under title of the form on the page defined
by this form. You cannot edit the display characteristics of title.

In the preceding example, the value of subtitle is Selectone of the following options

titleWidth

Defines the width in pixels of the value of title in the browser window.

The following table lists all elements that can occur within the form
body.

Table 2–10 Elements that Can Occur
within the Form Body

Component

Definition

Example

defun

Defines an XPRESS function. This element can be called by any field
element in a form.

<defun name=’add100’>

<def arg name=’x’/>

<add><i>x</i><i>100</i>

</add>

</defun>

defvar

Defines an XPRESS variable that is used to hold the results of a computation.

<defvar name=’nameLength’

<length>

<ref>fullname</ref>

</length>

</defvar>

Display

Identifies the display components that will define the appearance of
the field. See the section titled Display Element for
more information.

<Display class=’LinkForm’>

<Property name=’title’ value=’User
Self Service’/>

<Property name=’subtitle’ value=’Select
one of the following options’/>

</Display>

Field

Main element used within the form body. See the section titled Field Element for more information.

<Field name=’fullname’/>

FieldRef

Provides a reference to a field defined in an included form.

<FieldRef name=’fieldName’/>

Include

Provides a reference to another form object. Once included in the current
form, the fields defined in the form can be referenced and displayed.

<Include>

<ObjectRef type=’UserForm’
id=’#ID#UserForm:UserFormLibrary’/>

</Include>

FormRef

Provides a reference to another form object.

<FormRef name=’formName’/>

Namespace

Provides a way to define a shortcut to a view. The shortened name can
then be used in field names and references instead of the longer name. When
using the name substitution, use a colon (:) following the name.

<Namespace name=’w’ value=’waveset’/>

Form Element

The <Form> element must surround all Field elements
and contains the unique name of the form. The elements listed on the previous
page are contained within the beginning and ending Form tags.

Display Element

A Display element within the Form element
describes the component that will be used to render the form. By default,
this Display element is the used EditForm component. You
will rarely need to change the Form component class, but
you can set component properties. The two most common properties to specify
are title and subTitle.

EditForm also supports the adjacentTitleWidth property,
which can be used to set the width of the titles of adjacent fields. If this
property is not defined, it defaults to zero.

If you define adjacentTitleWidth as equal to zero,
columns titles will automatically resize. If set to a non-zero value, then
the title width of adjacent columns (for example, the second and third columns)
will be the value of adjacentTitleWidth.

Field Element

The Field element is the main element used within
the form body. Fields are used to define each of the user’s attributes.
You can use Field elements to include XPRESS logic in form fields. For more
information on working with form field elements, refer to the section titled Defining Fields.

The following example creates an editing field with the label Email
address.

The name of an editing field is typically a path expression within a
view that is being used with the form. In this example, waveset.email refers
to the email address associated with a user object in the Identity Manager repository.

Footer

The footer contains information about the Identity Manager object group
or organization with which the form is associated. It also contains the closing
tags for the </Form>, </Extension>,
and </Configuration> elements or other elements opened
in the header. The footer in the preceding example is:

<MemberObjectGroups> identifies the object group
or organization into which the system stores an object. If you do not specify
an object group, by default the system assigns the object to the Top organization.
For Configuration objects that contain forms, are typically found in the All
group with this syntax:

What Is a Form Field?

The form body contains Field elements that define how each element of
the Web page appears and behaves. Each Field can contain other fields, each
with its own display component.

Form fields comprise several parts, which are encapsulated by the <Field>
tag set:

Value Expressions. The
field can contain a number of XPRESS expressions, which calculate the value
of the field or define the set of allowed values. For example, <Default> is used to define the default value of a field, and <Derivation> is used to derive the value for the field when the form is first
loaded. Not all field elements contain expressions. See the section titled Field Display Properties.

HTML Display Components.
Display components determine how visible elements are displayed. In Identity Manager form
fields, display components (defined in the form by the <Display> element) determine the behavior and appearance of form
fields. You can specify only one display component for each field. These display
components are described in detail in Chapter 7, HTML Display Components

Disable Expressions. Fields
can be conditionally included in the form by using Disable expressions.
If the Disable expression evaluates to true, the field
is ignored.

Creating Variables

Use the following syntax to include variables that contain long lists
of constant or static data. This syntax builds a static list once and reuses
it on each reference

The former syntax is preferable to <list><s>Alabama</s>...</list>, which builds a new list each time it is referenced.

Note –

You must use balanced parentheses in form variable values and
when naming Identity Manager objects. If you use parentheses in object names
or form variables, they must be balanced (that is, for every ’(’
there is a corresponding ’)’). This allows all form variable expansions
to expand properly. (Unbalanced parentheses will result in an error.)

For example, when a resource name contains unbalanced parentheses, you
can neither edit or delete the user object of any user to whom this resource
has been assigned. However, the pertinent error message will indicate that
the failure is caused by unbalanced parentheses in the specific resource name.

Defining Fields

This section describes procedures you perform when customizing any form.
These procedures include:

Defining field names

Defining field elements

Adding a visible field

Hiding a field. 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.

Disabling a field. 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.

Setting a field value

Calling functions

The following sections discuss in more detail the field characteristics
you will set.

Defining Field Names

You use the field name to match the attribute defined on the resource
to the text entry field that is displayed on the web page. When the resource
is defined, the system sets up a schema map that maps resource account attributes
to Identity Manager attributes. For example, your Active Directory resource
might have attributes that include firstname, lastname, and Office Phone. When referring to these attributes
in the form, you must know the name of the attribute on the Identity Manager schema
plus the path to the attribute from the view.

There are two ways of defining the name attribute of the Field element:

The name attribute typically contains a path to an attribute
within the user view.

The name attribute is used to identify the field so that it
can be referenced by other fields in the form or by a FieldRef element.
This occurs when fields are defined to represent containers of other fields
and do not correspond to any one attribute of the view.

Determining whether a Field name represents a path
expression for the view or is simply a reference name depends on the value
of the class attribute selected in the Display element. If the display class
is the name of an editing component class, then the name is expected to be
a path expression for the view. See the section titled HTML Display Components for a detailed explanation of the component classes.

Creating a Path Expression to a View Attribute

Typically, you define a Field name by including the path to an attribute
in the user view (the path expression). For a list of these attributes, see Chapter 3, Identity Manager Views.

The following field definition renders a text field to edit the Identity Manager email
address:

The string accounts[Active Directory].email is
a path expression to another location within the user view that holds information
about account attributes for a specific resource. In this example, the resource
named Active Directory.

Example:

This example field defines the email address for all resources including Identity Manager that
contain an attribute named email on the left side of the schema map.

Identifying the Field for Reference

Naming a field provides you a way to reference the field value in other
fields. Use the <ref></ref> tag set to reference
a field value from another field. The following example concatenates into
the fullname field the firstname and lastname field values with a string, a comma, and a space such as: lastname, firstname. The <s> tag designates
a string.

Not all Field names represent path expressions for
the view. Some fields are defined to represent containers of other fields
and do not correspond to any one attribute of the view. In these cases, the Field name is used to identify the field so that it can be referenced
by a FieldRef element. If the field does not need to be
referenced, you do not need to specify the name.

For example, a form button performs an action, but does not contain
a value or need to be referenced by another form. Therefore, it does not need
a field name:

Field Display Properties

The Display element is common to all visible form
fields. Display elements contain Property elements that
define the characteristics of the field rendered by the browser. By defining
a Display element for a form, it will be visible on the
screen unless there is a Disable element in the field that
evaluates to true. There can be conditions in which the form is displayed
until another field or value is set and when the form recalculates the field
can become hidden from the screen. See the section titled Disabling Fields.

Display

Describes class and properties of the visible field. This element specifies
a component class to instantiate and a set of property values to assign to
the instance.

The class attribute of the Display element
must be the name of a Component class. By default, these classes are expected
to reside in the com.waveset.ui.util.html package and include
Applet, Button, and DatePicker among others. A list of all the default classes
and their descriptions can be found in the Base Component Class section
of Chapter 7, HTML Display Components To
reference a class that is not in this package, you must use a fully qualified
class name for the class attribute. All classes described in this document
are in the default package and do not require qualified names.

Property

Occurs within the Display element. The property value defines the names and values of properties that are to be
assigned to the component. The property name is always specified with the
name attribute.

Specifying Property Values for a Display Element

You can specify the Property value for a Display element through the use of:

a value attribute

an XML Object language

an expression to specify a value

For most property values, you can use the value attribute
and let the system coerce the value to the appropriate type.

Use of the value Attribute

The most common way of specifying the property value is with the value
attribute. The value of the value attribute is treated as a string, but if
necessary, the system will coerce it to the data type desired by the component.
In the previous example, the property size is set to the
integer value 20, and the property maxLength is set to
the integer value 100.

The following example creates a field that uses SimpleTable to
organize several subfields. Within XML forms, the most common Container components
used are SimpleTable and ButtonRow.

Within the Display element are zero or more Property elements. These define the names and values of properties that
are assigned to the component. The Property name is always
specified with the name attribute. The property value is most specified with
the value attribute. The value of the value attribute
treated as a string, but if necessary it will be coerced to the data type
desired by the component.

Use of the XML Object Language

You can also specify property values using the XML Objects language.
This approach is useful primarily when specifying list values. This language
provides a syntax for describing several standard Java objects as well as
other objects defined by Identity Manager.

The more common Java XML objects include:

List

Map

MapEntry

String

Integer

Boolean

Object

When you use the XML Object syntax to specify property values, an element
is placed inside the Property element. For more information
on the XML Object language, see Chapter 6, XML Object Language.

All properties that expect list values recognize the List element.
Most attributes, in addition, recognize the comma list syntax for specifying
lists.

Use of an Expression to Calculate the Value

You can also specify a Property value through an
expression. This allows a value to be calculated at runtime, possibly combining
fixed literal values with variable values defined by the page processor. Example:

Example 2–8 Property Value

In the preceding example, waveset.accountId is a
reference to a variable. When the system generates the HTML for this component,
the page processing system supplies the value for the waveset.accountId variable.
The names of the variables that can be referenced are defined by the page
processor. In most cases, these are defined by a view that is used with the
XML form. Form designers must be aware of the view with which the form will
be used and only reference attributes defined by that view.

Disable Element

Calculates a Boolean value. If true, the field and all its nested fields
will be ignored during current form processing.

Do not create potentially long-running activities in Disable elements.
These expressions run each time the form is recalculated. Instead, use a different
form element that will not run as frequently perform this calculation.

Note –

The display.session and display.subject variables
are not available to Disable form elements.

Example

This example illustrates a field definition that uses an expression
within the <Disable> element to control the visibility
of the field. accountInfo.typeNames is used to find the
type of all resources that a user is assigned to. The type returned is a list
of all the user’s resource types. If the list of returned type names
contains Solaris, then this field is displayed on the screen. Otherwise, this
field is disabled.

Default Element

Calculates a value to be used as the value of this field, but only if
the field does not already have a non-null value. Default is
essentially the same as Derivation, except that the value
applies only if the current value is non-null. Default expressions are calculated
when:

the form is first loaded

data is retrieved from one or more resources

the form is recalculated or saved until the field value is
non-null.

Example

This example shows a field definition that uses string manipulation
expressions to return a default account ID composed of the first initial of
the first name plus the user’s last name.

Derivation Element

Unconditionally calculates a value for the field. Whenever a Derivation
expression is evaluated, the current field value is replaced.

Derivation expressions are calculated when the form is first loaded
or data is returned from one or more resources

The following example shows a field definition that uses conditional
logic to map one set of values into another set. When this field is processed,
the expression in the <Derivation> element is evaluated
to determine the descriptive value to be displayed for this field based on
the location code returned from the resource.

Expansion Element

Unconditionally calculates a value for the field. It differs from Derivation
in the time at which the expression is evaluated.

Expansion statements are calculated when:

the page is recalculated

the form is saved

The following example shows a field definition that uses conditional
logic to convert the value derived for the location field
in the previous example back into a three-letter abbreviation that will be
stored on the Oracle resource. Notice the difference in the field names. The
location field value is not saved on any resource. It is used to calculate
another field.

The name of an editing field is typically a path expression within a
view that is being used with the form. In the preceding example, waveset.email refers to the email address associated with a user object in the Identity Manager repository.

A Container field may not have a name and is always
used with one of the Container components, such as ButtonRow, SimpleTable, or EditForm.

One common type of container is the EditForm container,
which builds an HTML table that contains titles in one column and components
in another. These titles are defined in the title property
and are rendered on the Identity Manager page associated with the form.

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
or incorporated in to any global.* attributes. If the view
already contains a value for the disabled field, the value will not be modified.

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.

Setting Default Values

You can set the email address based on the user’s first initial
and the first seven characters of the user’s last name. In this example,
the system performs an additional check to ensure that the values have been
set before performing the concatenation. This additional check is performed
to:

Allow the email address to set only when the account is first
created.

Deriving Field Values

Some fields are used on the form solely to calculate other fields. These
fields cannot be stored on any resource to which the user belongs. When the
user record is edited, each of the resources is contacted and the field values
for the attributes are populated. To populate the fields that are used for
calculations, you can write derivation rules.

Example

A phone number field can be represented on the form as a single text
box. However, a more advanced form might have three fields for the area code
and phone number, which are used to calculate the phone number that is saved
to the resource.

In the simple case of representing a phone number, you can have form
fields that resemble the ones listed below.

Example

The following example expands on the field definition for the field
P1 defined above. It defines how a phone number attribute is read into the
form, and consequently expands into the three field displays.

When a user enters data into Identity Manager, the form can ensure the
data is entered properly. However, Identity Manager cannot ensure that data
entered directly into the resource meets the same requirements. For example,
over the years, administrators might have entered the phone number as 123-4567
(8 characters), 123-123-4567 (12 characters), or (123) 123-4567 (14 characters).

Example

The definition of the OfficePhone field remains the
same as described previously, but each of the three fields (P1, P2, and P3) should be updated to use derivation
rules, as this example illustrates for the P1 field.

When you are calculating fields, you must consider the data’s
current format and quality in the resource. It is much easier to ensure the
correct field values when creating new users. It is much harder to get existing
data to conform to the field when reading it off the resource. You can use
derivation rules for any field to check the format of the attribute as it
is being read in.

Recalculating Fields

The system performs field calculations many times when a user is working
on a form. The field is calculated when it is first displayed, which sets
any default values, and the form is calculated when the user clicks Save. Two other actions can cause the form to be
evaluated: clicking Recalculate on the
Edit User page and action fields.

Example

To ensure that the system recalculates the value of a field, set action to true in the Display class element as shown below:

<Display class=’Select’ action=’true’>

Add this value only to fields that the user selects or clicks on. Do
not add it to test or text area fields. When a field has action=true set,
the form recalculates this form whenever the field is modified in the browser.

Guidelines for Structuring a Form

Use the following guidelines when creating the structure of your new
form or editing an existing form.

List field elements in the order in
which you want them displayed on the page. The order of the field
elements in the form determines the order in which the elements are displayed
in the browser.

Place the referenced field before
the field referencing it. If a field has an expression that references
a value in another field, place the referencing field after the
referenced field.

Disabled fields are ignored when logically
true. If any field defines a Disable expression, it is evaluated.
If the result of the Disable expression is logically true, the field will
be ignored during form evaluation.

Optimizing Expressions in Form Fields

Some activities performed in forms can call out to resources external
to Identity Manager. Accessing these resources can affect Identity Manager performance,
especially if the results are long lists of values (for example, compiling
a list of groups or email distribution lists). To improve performance during
these types of calls, follow the guidelines in the section titled Using a Java Class to Obtain Field Data.

Example Scenario

The following example illustrates a type of expression optimization.

If you want to query a database for information that is not stored in Identity Manager or
accessible as a resource account attribute, follow these general steps:

To Perform Optimizing Expressions

Write a Java class that performs the database
access.

Define a form field that uses a default expression to call the
Java class.

Reference the hidden variable.

Using a Java Class to Obtain Field Data

You will need to write a Java class that has methods that can be called
to retrieve information. The example in the following section, Defining
a Hidden Form Field, uses the getJobGrade method,
which is a custom method. You should locate this custom class in the idm\WEB-INF\classes\com\waveset\custom directory structure. (If these directories do not exist on your
system, you must create them.)

Follow these guidelines when writing this class:

If the method performs an expensive operation, such as a database
request, you should make the call in the Default expression of a hidden form
field. This will cause the value to be stored in the view when the form is
first loaded. The value can then be referenced many times without incurring
database overhead.

If the method being called has not been declared static, use
the new element to instantiate the class first, as shown in the following
example.

Defining a Hidden Form Field

First, define a hidden form field that uses a default expression to
call the Java class by not including any Display class
in the field definition:

Default expressions are evaluated only if the view does not contain
a value for the attribute jobGrade. Once the default expression
has been run, the result is stored in jobGrade, and the expression is not
run again.

To Define a Hidden Form Field

Select Hidden from the Display Class menu.

Click OK.

The Hidden
display class corresponds to the <input type=hidden’/> HTML
component. This component supports only single-valued data types because there
is no way to reliably serialize and deserialize multi-valued data types.

If you have a List that you want to render it as a string, you must
explicitly convert it to a String, as shown in the following example:

Referencing the Hidden Attribute

You can use XPRESS defvar variables to hold the results
of a computation, but the results are typically not as efficient as using
a hidden form field.

Note about Optimizing Variables Beyond a Single Iteration

XPRESS variables typically persist for only a single iteration over
the form fields. As a result, you can use a variable within an Expansion phase
but not on a subsequent Derivation phase. If you need a computed value to
remain relevant beyond one field iteration, use a hidden form field instead.
Hidden field values are stored in the view and will persist until the editing
session is either canceled or saved.

Disabling Automatic Linking of New Resources and
Users

Identity Manager provides a way to control the linking of existing accounts
when new resources are assigned to a user.

When you assign a new resource to a user, and an account with the assigned
ID already exists on the resource, Identity Manager by default automatically
links that account to the Identity Manager user and proceeds with provisioning.
Alternatively, you can disable this automatic linking and enter an alternative
account ID when creating a new account for the user.

There are two ways to control how new accounts are linked to user:

Enabling manual linking of this information in the user form

Preventing automatic linking during provisioning

Enabling Manual Linking in the User Form

To enable manual linking, you must

Include a property definition in each user form similar to
the following

To reference this field, you must have the following Include statement
in your user form. Typically, this Include is present in all user forms.

<Include>
<ObjectRef type=’UserForm’ name=’User Library’/>
</Include>

With these form changes in place, Identity Manager checks for existing
accounts each time the form is refreshed, and before it is saved. If Identity Manager discovers
an existing account, it displays warning messages at the top of the form,
and inserts new fields for each discovered account. These new fields include
a checkbox that can be used to manually indicate that the account should be
linked.

In addition, Identity Manager generates a field for each attribute in
the resource’s Identity template. With this field, you can specify a
different identity for the account. Identity Manager fetches the attribute
for the existing accounts and includes it in the view.

You can display these attributes using the MissingFields reference
or with your own custom fields. You must either supply an alternative identity
for an account that does not exist, or check the option to allow the existing
account to be linked before the form can be saved.

Preventing Automatic Linking during Provisioning

When performing non-interactive provisioning from a workflow, you can
also control whether Identity Manager performs automatic account linking. Passing
the NoLinking view option to the checkinView call
prevents automatic linking. You can specify this option in several ways:

Setting the option as attributes in the view. In this case,
name the view attribute viewOptions.NoLinking. You can
then set it in a workflow with XPRESS logic like this:

<set name=’user.viewOptions.NoLinking’>
<s>true</s>
</set>

Preventing an Attribute from being Displayed in Clear
Text on Results Pages

Identity Manager displays the value of an attribute in clear text on
Results pages, even when you have set the attribute for display with asterisks
in an Edit form.

To prevent an attribute from being displayed in clear text on Results
pages, you must register it as a secret attribute. To register a secret attribute,
add it as follows to the System Configuration object:

Referencing Fields from Another Form

You can reference particular fields in a separate form (rather than
a complete form) through the use of the <FieldRef> element.

Use the <FieldRef> element to include a specific
field from within an external form. Include:

the name of the form in which the field resides. This form
name must be listed in the include section of the form header with the <ObjectRef> element. The property type specifies the name of the form (UserForm) and its unique configuration ID. The name property identifies
the name of the field you will later reference.

the field name itself inserted in the section of the form
that matches the location on the page you would like it to be displayed.

Implementing the Identity Manager Whitelist Feature

You can use the whitelist feature to check forms and workflows that
use the SaveNoValidate action against a list of IDs or form names. Identity Manager checks
the whitelist for either form names or form-owner IDs. The list of IDs, called
saveNoValidateAllowedFormsAndWorkflows, is located in the security attribute
in the System Configuration object. If the form name or owner ID is on the
whitelist, the form or workflow can use the SaveNoValidate action. If the
form name or the owner ID is not on the list, the form or workflow is processed
using a Save action. If the list is not present, all forms and workflows can
be processed as SaveNoValidate.

To implement this feature in your deployment, you must add any forms
or workflows using SaveNoValidate to the saveNovalidateAllowedFormsAndWorflows
list in the System Configuration object. To see the IDs or form names that
you must add, check the syslog or turn trace level 4 on for com.waveset.ui.util.GenericEditForm
and submit any custom forms or workflows that use SaveNoValidate. Identity Manager will
log a warning including the ID. If you are getting “null” form
names in the syslog, confirm that the form in the TaskDefinition that was
run has a name attribute.