Sun Identity Manager Deployment Reference

Chapter 2 Identity Manager Forms

This chapter describes how you can customize the appearance and behavior of selected pages in SunTM Identity Manager Administrator and User Interfaces by customizing the forms that define these pages.

You can use the Identity Manager IDE to view and edit Identity Manager forms and other generic objects. Instructions for installing and configuring the Identity Manager IDE are provided on https://identitymanageride.dev.java.net.

This chapter is organized into the following sections:

Refer to the following chapters for related information:

Understanding Forms

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

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

This section covers the following topics:

What Are Forms?

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

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

What Forms Control

Forms control the following objects and activities:

Sample Form

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


<Field name=’waveset.accountId’/>
   <Display class=’text’>
     <Property name=’title’ value=’AccountID’/>
   </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:

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

Example Scenario

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

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

Identity Manager Pages that Use Forms

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

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

Table 2–1 Pages and Associated JSPs and Forms

Page You Want to Edit 

Associated JSP 

Associated Form 

Create/Edit User 

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:

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


Note –

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


Change Password Forms

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

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

End User Menu Form

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

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


Note –

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


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


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


<Configuration id=’#ID#Configuration:EndUserTasks’ name=’End User Tasks’>
<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.


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

<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:

Tabbed User Form contains these fields:


Note –

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

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

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


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

End User Form

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

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

Approval Form

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

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

You can customize Approval Form to:

How Do Forms Work?

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

User View and Forms

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

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

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

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

Undefined Attributes

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

Form Evaluation

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Empty Forms

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


Example 2–2 Empty Form Object


<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’>
<Configuration wstype=’UserForm’name=’Empty Form’>
   <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

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.


Active Sync Forms

Active Sync-enabled adapters typically use two types of forms during processing: a resource form and a user form.

Form processing occurs in three steps:

Procedure How Active Sync Forms Are Evaluated

  1. Active Sync fields are filled in with attribute and resource information. Use the activeSync namespace to retrieve and set attributes on the resource.

  2. The resource form is expanded and derived. During this expansion, all user view attributes are available.

  3. The user form is expanded and derived.

    The $WSHOME/sample/forms directory provides sample forms that end with ActiveSyncForm.xml. They include logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Identity Manager user when a deletion is detected on the resource.

ActiveSync User Forms

Identity Manager uses two forms when processing ActiveSync user events:

Resource Form

The resource form is the form that the administrator selects from a pull-down menu when the resource is created or edited. A reference to a selected form is stored in the resource object.

Resource forms are used with Active Sync-enabled adapters in the following ways:

Resource forms include logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Identity Manager user when a deletion has been detected.

User Form

The user form is used for editing from the Identity Manager interface. You assign it by assigning a proxy administrator to the adapter. If the proxy administrator has a User form associated with him, this form is applied to the User view at processing time.

Proxy Administrator and the User Form

You set a proxy administrator for an adapter through the ProxyAdministrator attribute, which you can set to any Identity Manager administrator. All Active Sync-enabled adapter operations are performed as though the Proxy Administrator was performing them. If no proxy administrator is assigned, the default user form is specified.

Alternative Form to Process Attributes

Best practice suggests keeping common changes, such as deriving a full name from the first and last name, in the User form. The resource form should contain resource-specific changes, such as disabling the user when their HR status changes. However, you can alternatively place it in an included form after the desired attributes are placed in a common path, such as incoming.

ActiveSync Form Processing

An overview of ActiveSync form processing includes the following phases:

End-User Forms

The forms discussed in this section are found in the end-user interface.

End-User Delegation Forms

In the end-user interface, you can access the following forms from the Delegations tab:

End User View WorkItem Delegations Form

This form consists of a single table that shows all current and past delegations. You can filter this table based on delegation status. Valid status values include Current, Upcoming, and Ended. Users can terminate current delegations, create new delegations, and edit existing delegations.

To configure the list of past delegations displayed by this form, you can set the delegation.historyLength attribute in the SystemConfiguration object. For more information, see the Editing Configuration Objects chapter of the Deployment Guide. To configure other aspect of this forms’s behavior, see the Delegate WorkItems View in the Views chapter of this guide.

End User Delegate WorkItems Form

This form is used to create new and edit existing delegations.

End User Anonymous Enrollment Forms

Users use this set of forms when requesting an Identity Manager account if they do not have one.

Customizing Forms

After familiarizing yourself with the default operation of the Identity Manager product, you can identify pages you’d like to customize.

ProcedureTo Customize a Form

  1. Consult the section titled Edited Forms for a list of editable pages and their corresponding forms.

  2. To edit a form, launch the Identity Manager IDE and select Open Repository Object. Select the form you want to edit from the popup dialog that is displayed.

    This section covers the following topics:

Overview of Customization

You can customize a form to make it more user-friendly, change its display characteristics, or include logic for processing field data.

Basic Steps

The basic steps for customizing any form in the Identity Manager system include:

Typical Tasks

When you edit a form, you typically perform the following tasks:

Table 2–2 Form Elements

Property  

Description  

Title 

Specifies the text that displays adjacent to the form field. 

Class 

Identifies the HTML display class to which the element belongs. 

Required 

Identifies whether the element is required to process the form. This field must have a non-null value upon submission. When set, results in a red asterisk appearing to the right of the field. Message text at the bottom of the form indicates that red asterisk denotes fields that must have a value for submission to proceed. 

Action 

When set, a change causes the page to refresh any Select or MultiSelect controls. In the Identity Manager Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set.

No New Row 

Used strictly for form layout. When true, forces the field to appear to the right of the proceeding field. For example, Name fields are examples where this is useful, where it is desirable to allow the user to enter the last name, first name, and middle initial from right to left, rather than down the page. 

Hidden 

Indicates the field should not be visible to the user. The field is typically used to set attribute values that are calculated form other fields, such as constructing the full name from a concatenation of first and last name. 

Title 

Controls the character width of the control (text boxes). 

Class 

Specifies the character width of the control buffer (text boxes). Characters scroll if the user types in a string greater than the value specified by the size property.

Required 

Identifies the name for this form field, typically a path expression in to the view that is used with this form. 

Set the characteristics in the following table from the Main tab view.

Table 2–3 Characteristics Set from Main Tab View

Field  

Description  

Name 

Enter the name for this field. A field name is typically a path expression into the view that is being used with this form. All fields that display as editing components (such as text boxes, checkboxes, and selects) must have a name that specifies a view path. Fields that do not display as editing components (such as SectionHead and Javascript) do not require names. However, you can give non-editing fields names if they need to be referenced by another form through a Field reference.

Title 

Enter a title for the field. This title displays adjacent to the field on the form. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button.

Sub Title 

(Optional) Specify text that Identity Manager can display beneath the form title. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button.

Help Catalog 

Enter the help key that associates guidance help with the field. This value is the name of an entry in an associated help catalog specified by the form. Specifying a help key causes an icon to appear to the left of the field. Moving the mouse over the icon causes the text referenced in the help catalog to display. 

Base Context 

(Not typically used in standard user forms.) Enter the base context to avoid the need to specify the full path in every field. Base context identifies the underlying Map (specifically, com.waveset.object.Genericobject and is typically named user or userview. In the Identity Manager Administrator Interface, the editing context is user, so the base context reference is left blank. In forms launched from manual actions, such as approvals, the workflow context is the context of the form.

Options 

Select one or more display options for the field: 

Required– Identifies whether the element is required to process the form. This field must have a non-null value upon submission. When set, results in a red asterisk appearing to the right of the field. Message text at the bottom of the form indicates that red asterisk denotes fields that must have a value for submission to proceed.

Button– Causes the field to display in a single, horizontal row at the bottom of the form. Otherwise, it displays on the next line of the form. This is most set with fields that use the display class Button.

Action– When set, a change causes the page to refresh any Select or MultiSelect controls. In the Identity Manager Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set.

Library– Indicates that a field should only display when it is referenced, rather than when it is declared. This is useful when the order in which fields are evaluated on a form may differ from the order in which they are displayed to the user.

Default 

Specify an expression to calculate a default value for the field. The default expression is called before the form is displayed if the current value for this field is null. 

Derivation 

Specify an expression to calculate the value of a field before it is displayed. It is similar to a Default expression, except that it is evaluated even if the current field value is non-null. The derivation expression is evaluated before the form is first displayed, and then again each time the form is refreshed. 

Validation 

Specify logic to determine whether a value entered in a form is valid. Validation expressions return null to indicate success, or a string containing a readable error message to indicate failure 

Expansion 

Specify an expression to calculate the value of the field after the form has been submitted. Expansion expressions are typically used with fields that are also marked hidden. Since hidden fields are not directly editable by the user, the value can be calculated with an Expansion expression. See Hiding Fields.

Disable 

Specify an expression that, if evaluated to true, disables the field and any of its nested fields. A disabled field does not display on the form. It is used to determine if a user has a specific type of resource. If the user does, the form then displays the appropriate fields for that resource. 

Display Class 

Identify the HTML component class used to render this form component in the browser. By default, the Display Class selection is EditForm. If the form is a link form (such as the End User menu), then select LinkForm from the Display Class options. 

See the HTML Display Class table in Chapter 7, HTML Display Components

size 

Controls the character width of the control (text boxes). 

maxLength 

Specify the maximum number of characters for this element. 


Tip –

A field name is often a path expression into the view that is being used with this form, and is typically associated with a particular attribute on a resource. To browse a list of resources and their attributes, click Browse resources. The Browse resource dialog opens, displaying an expandable tree of resource types. Click the name of the resource type to display a list of resource instances and the names of their attributes. To use the name of resource attribute as your new form field name, click the resource attribute name, then click OK. This inserts the attribute name into the Name field.


Table 2–4 Options for Display Class

HTML Component  

Purpose  

Apple 

Inserts an applet reference into the page. 

BackLink 

Displays a link that returns to the previous page. 

BorderedPanel 

A container that organizes its components into 5 regions: north, south, east, west, and center. 

Button 

Displays a button. 

ButtonRow 

A container that arranges its components in a horizontal row with padding in between. Typically used to display a row of Button components 

CheckBox 

Arranges its components in a horizontal row with padding in between. Typically used to display a row of Button components. (Container) 

DatePicker 

Displays a calendar icon on the page. The user can click this icon to select a calendar date and populate a page field. 

EditForm 

The default container for forms. Displays component titles in one column and components in another. Each row has an alternating gray or white background. 

FileUpload 

Variant of the Text component used for specifying the name of a file to be uploaded. 

Hidden 

A component used to include data into the HTML page that is not displayed 

Html 

Inserts pre-formatted HTML into the page. 

Javascript 

Defines JavaScript functions. 

Label 

Displays read-only text. 

Link 

Places a link on the page. 

LinkForm 

Places components in a bulleted vertical list with no titles. Typically used for pages that contain lists of Link components. Alternative to EditForm container. (Container) 

MultiSelect 

Displays a multiselection box, which displays as a two-part object in which a defined set of values in one box can be moved to a “selected” box. 

NameValueTable 

Displays a list of name/value pairs in a simple table with a beige background. 

Panel 

Organizes its components in either a horizontal or vertical line.(Container) 

Radio 

Displays 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. 

SectionHead 

Displays a section heading. These are recognized by the EditForm container to and are rendered in bold text that spans both the title and component columns. 

Select 

Displays a single-selection list box. 

SimpleTable 

Arranges components in a simple grid with a row of column titles. 

SubTitle 

Identifies the text that displays below the form title. 

Text 

Displays read-only text. 

TextArea 

Places a link on the page. 

Title 

Identifies the text that displays at the top of the form. 

Table 2–5 Form Elements

Form Element  

Description  

Name 

Enter the name for this field. A field name is typically a path expression into the view that is being used with this form. All fields that display as editing components (such as text boxes, checkboxes, and selects) must have a name that specifies a view path. Fields that do not display as editing components (such as SectionHead and Javascript) do not require names. However, you can give non-editing fields names if they need to be referenced by another form through a Field reference.

Title 

Enter a title for the field. This title displays adjacent to the field on the form. Select the data type of this element from the drop-down menu immediately adjacent to this field. To edit the text displayed in this field, click the adjacent Edit button.

Help Key 

Enter the help key that associates guidance help with the field. This value is the name of an entry in an associated help catalog specified by the form. Specifying a help key causes an icon to appear to the left of the field. Moving the mouse over the icon causes the text referenced in the help catalog to display. 

Options 

Select one or more display options for the field: 

Required– An entry or selection in this field is required to process the form.

Button– Causes the field to display in a single, horizontal row at the bottom of the form. Otherwise, it displays on the next line of the form. This is most set with fields that use the display class Button.

Action– When set, a change causes the page to refresh any Select or MultiSelect controls. In the Identity Manager Administrator Interface, this causes the underlying view to be refreshed. Role selection exemplifies this behavior. When a new role is selected in the Tabbed User Form, the view is refreshed to reflect the resources that are assigned through that role during that edit session. After the view has been refreshed, resource account attributes on those newly assigned resources can be explicitly set.

Library– Indicates that a field should only display when it is referenced, rather than when it is declared. This is useful when the order in which fields are evaluated on a form may differ from the order in which they are displayed to the user.

Default 

Specify an expression to calculate a default value for the field. The default expression is called before the form is displayed if the current value for this field is null. 

Derivation 

Specify an expression to calculate the value of a field before it is displayed. It is similar to a Default expression, except that it is evaluated even if the current field value is non-null. The derivation expression is evaluated before the form is first displayed, and then again each time the form is refreshed. 

Validation 

Specify logic to determine whether a value entered in a form is valid. Validation expressions return null to indicate success, or a string containing a readable error message to indicate failure. Validation rules are evaluated only when a form is submitted, not after each refresh or recalculate. 

Expansion 

Specify an expression to calculate the value of the field after the form has been submitted. Expansion expressions are typically used with fields that are also marked hidden. Since hidden fields are not directly editable by the user, the value can be calculated with an Expansion expression. 

Disable 

Specify an expression that, if evaluated to true, disables the field and any of its nested fields. A disabled field does not display on the form. It is used to determine if a user has a specific type of resource. If the user does, the form then displays the appropriate fields for that resource. 

Display Class 

Identifies the HTML component class used to render this form component in the browser. By default, the Display Class selection is EditForm. If the form is a link form (such as the End User menu), then select LinkForm from the Display Class options. 

See the HTML Display Class table in Chapter 7, HTML Display Components

value 

Specifies the property attribute. Typically is a string. 

Variable 

Identity Manager assigns a scope to all <Variable> elements when the element is declared. If you do not assign a value to the scope attribute, Identity Manager assigns it a value of local, which means that the variable can be accessed only within the XPRESS section that it is declared in.

Additional Variable attributes that define scope include:

  • input – Declares that the <Variable> element has local scope and that the value can be initialized by the caller.

  • output – Declares that the <Variable> element has local scope but can be returned to the caller.

  • external – Declares that the <Variable> element has non-local scope – that is, assignments to this variable will result in assignment to this variable in the scope it was first declared in.

maxLength 

Specifies the maximum number of characters for this element. 

Table 2–6 Default Services in Forms Toolbox

Service  

Description  

Text 

Displays a regular text entry box. 

Secret Text 

Displays text as asterisks (*). Typically used for encrypted data like passwords 

Select 

Displays a single-selection list box. Values for the list box must be supplied by the allowedValues property.

MultiSelect 

Displays a multiselection text box, which displays as a two-part object in which a defined set of values in one box can be moved to a selected box. Values in the left box are defined by the allowedValues property, values are often obtained dynamically by calling a Java method such as FormUtil.getResources. The values displayed in the right side of a multiselection box are populated from the current value of the associated view attribute, which is identified through the field name.

Checkbox 

Displays a checkbox. When checked, the box represents a value of true. An unselected box represents a false value.

Label 

Displays a multi-line text entry box 

TextArea 

Displays 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. 

Radio 

Places a link on the page. 

Link 

Displays a button. 

Button 

Refers to a variable that is defined by the view that is used with this form. 

accountId 

Displays a multi-line text entry box 

Additional Customization-Related Topics

The following topics are covered in this section:

Form Structure

Forms are stored as XML objects within the Identity Manager repository. Each form is stored as its own object with the following structure.


Note –

You do not need to know the XML structure of a form. Identity Manager IDE simplifies working with form structure. This information is supplied for your reference only.


The following stub form illustrates the general structure of a form.


Example 2–3 Form Structure


<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’>
<!--  id="#ID#UserForm:EndUserMenu" name="End User Menu"-->
<Configuration id=’#ID#UserForm:EndUserMenu’ name=’End User Menu’
reateDate=’1012185191296’ lastModifier=’Configurator’
lastModDate=’1013190499093’ lastMod=’44’ counter=’0’ wstype=’UserForm’>
   <Extension>
   <Form name=’End User Menu’>
      <Display class=’LinkForm’>
         <Property name=’title’ value=’User Self Service’/>
         <Property name=’subtitle’ value=’Select one of the following options’/>
      </Display>
Field content
   </Form>
   </Extension>
<MemberObjectGroups>
   <ObjectRef type=’ObjectGroup’ id=’#ID#Top’ name=’Top’/>
   </MemberObjectGroups>
</Configuration>

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:

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. 

Configuration id=’#ID#UserForm:EndUserMenu’ name=’End User Menu’ createDate=’1012185191296’ lastModifier=’Configurator’ lastModDate=’1013190499093’ lastMod=’44’ counter=’0’ wstype=’UserForm’>

Form Body

The form body is composed of:

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 Select one 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.


Example 2–4 Sample Form Element


<Form name=’Create User Form’
   <Field name=’waveset.accountId’>

additional fields

</Form>

Additional example:

<Form name=’Task Launch Form’>
   <Display class=’EditForm’>
      <Property name=’title’ value=’Task Launch’/>
      <Property name=’subTitle’ value=’Enter task launch parameters’/>
   </Display>
...
</Form>

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.

<Form name=’Default User Form’ help=’account/modify-help.xml’>
   <Display class=’EditForm’>
     <Property name=’titleWidth’ value=’120’>
     <Property name=’adjacentTitleWidth’ value=’60’>
   </Display>

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.

<Field name=’waveset.email’>
   <Display class=’Text’>
      <Property title=’Email Address’/>
      <Property size=’60’/>
      <Property maxLength=’128’/>
   </Display>
...
</Field>

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:

</Form>
</Extension>
   <MemberObjectGroups>
      <ObjectRef type=’ObjectGroup’ id=’#ID#Top’ name=’Top’/>
   </MemberObjectGroups>
</Configuration>

<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:

<MemberObjectGroups>
   <ObjectRef type=’ObjectGroup’ name=’All’/>
</MemberObjectGroups>

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:

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

<defvar name=’states’>
    <List>
      <String>Alabama</String>
            ...
    </List>
</defvar>

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:

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:

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:

<Field name=’waveset.email’>
   <Display class=’Text’>
      <Property name=’size’ value=’60’/>
   </Display>
</Field>

The string waveset.email is a path expression for the user view that targets the email address stored in the Identity Manager repository.

Example:

This example field edits the email address defined for a particular resource account. The field name references a resource in the account:

<Field name=’accounts[Active Directory].email’>
   <Display class=’Text’>
      <Property name=’size’ value=’60’/>
   </Display>
</Field>

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.

<Field name=’global.email’>
   <Display class=’Text’>
      <Property name=’size’ value=’60’/>
   </Display>
</Field>

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.


Example 2–5 Referencing Fields


<Field name=’global.firstname’>
   <Display class=’Text’/>
</Field>
<Field name=’global.lastname’>
   <Display class=’Text’/>
</Field>
<Field name=’global.fullname’>
   <Expansion>
      <concat>
         <ref>global.lastname</ref><s>, </s>
         <ref>global.firstname</ref>
      </concat>
   </Expansion>
</Field>

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 class=’Button’>
      <Property name=’label’ value=’Recalculate’/>
      <Property name=’command’ value=’Recalculate’/>
   </Display>
</Field>

For more information on user views, see the section titled User View and Forms.

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.

<Display class=’Text’>
   <Property name=’size’ value=’20’/>
   <Property name=’maxLength’ value=’100’/>
</Display>

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:

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.


Example 2–6 Field that Uses the SimpleTable Element


<Field name=’SelectionTable’>
   <Display class=’SimpleTable’>
      <Property name=’columns’>
         <List>
            <String>Account</String>
            <String>Description</String>
         </List>
      </Property>

   </Display>
<Field name=’accounts[LDAP].selected’>
   <Display class=’Checkbox’>
      <Property name=’label’ value=’LDAP’/>
   </Display>
</Field>
<Field>
   <Display class=’Label’>
      <Property name=’text’ value=’Primary Corporate LDAP Server’/>
   </Display>
</Field>
<Field name=’accounts[W2K].selected’>
   <Display class=’Checkbox’>
      <Property name=’label’ value=’Windows 2000’/>
   </Display>
</Field>
<Field>
   <Display class=’Label’>
      <Property name=’text’ value=’Primary Windows 2000 Server’/>
   </Display>
</Field>
</Field>

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:

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.


Example 2–7 Property Element


<Property name=’size’>
   <Integer>10</Integer>
</Property>

<Property name=’title’>
   <String>New Password</String>
</Property>

<Property name=’leftLabel’>
   <Boolean>true</Boolean>
</Property>

<Property name=’allowedValues’>
   <List>
      <String>Texas</String>
      <String>Iowa</String>
      <String>Berkshire</String>
   </List>
</Property>

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


<Property name=’title’>
   <concat>
      <s>Welcome </s>
      <ref>waveset.accountId</ref>
      <s>, select one of the following options.</s>
   </concat>
</Property>

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.


<Field name=’HomeDirectory’ prompt=’Home Directory’>
   <Display class=’Text’/>
      <Disable>
         <not>
            <contains>
               <ref>accountInfo.typeNames</ref>
               <s>Solaris</s>
            </contains>
          </not>
   </Disable>
</Field>

Disable elements are typically used to check values of other fields on the form. Often the other field being referenced is calculated based on other input fields.

<Field name=’special value subfield’>
   <Comment>Show only when otherField has the value ’special value’</Comment>
   <Disable>
      <neq>
         <ref>otherField</ref>
         <s>special value</s>
      </neq>
   </Disable>
</Field>
<Field name=’account correlation rule’>
   <Comment>If synchronization on a resource supports an account correlation rule,
allow one to be selected, otherwise don’t show the field.  If a process rule has been
selected, then a correlation rule won’t be run, so don’t show the field.</Comment>
   <Disable>
      <or>
         <isnull>
            <ref>resourceAttributes[correlationRule].displayName</ref>
         </isnull>
         <notnull>
            <ref>resourceAttributes[processRule].value</ref>
          </notnull>
      </or>
         </Disable>
   </Field
...
</Field>>

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:

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.


<Field name=’waveset.accountId’>
   <Display class=’Text’>
      <Property name=’title’ value=’AccountID’/>
   </Display>
   <Default>
      <concat>
         <substr>
            <ref>accounts[AD].firstname</ref>
               <i>0</i>
               <i>1</i>
            <ref>accounts[AD].lastname</ref>
         </substr>
      </concat>
   </Default>
</Field>

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.


<Field name=’location’>
   <Display class=’Text’>
      <Property name=’title’ value=’Location’/>
   </Display>
   <Derivation>
         <switch>
            <ref>accounts[Oracle].locCode</ref>
            <case>
               <s>AUS</s>
               <s>Austin</s>
            </case>
               <s>HOU</s>
               <s>Houston</s>
            </case>
            <case>
               <s>DAL</s>
               <s>Dallas</s>
            </case>
            <case default=’true’>
               <s>unknown</s>
            </case>
         </switch>
   </Derivation>
</Field>

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 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.


<Field name=’accounts[Oracle].locCode’>
   <Expansion>
      <switch>
         <ref>location</ref>
         <case>
            <s>Austin</s>
            <s>AUS</s>
         </case>
         <case>
            <s>Houston</s>
            <s>HOU</s>
         </case>
         <case>
            <s>Dallas</s>
            <s>DAL</s>
         </case>
      </switch>
   </Expansion>
</Field>

Validation Element

Determines whether a value entered in a form is valid. Validation rules are evaluated whenever the form is submitted.

This example Validation rule checks to make sure that a user’s zip code is five digits.


<Validation>
   <cond>
      <and>
      <eq><length><ref>global.zipcode</ref></length>
            <i>5</i>
      </eq>
            <gt><ref>global.zipcode</ref><i>99999</i></gt>
      </and>
      <null/>
      <s>zip codes must be five digits long</s>
   </cond>
</Validation>

Editing and Container Fields

When the Display element appears with the Field element, it describes the component that will be used to render that field. There are two types of fields:

Editing fields must have names and are always used with one of the editing components such as Text or Checkbox.

Example Editing Field


<Field name=’waveset.email’>
   <Display class=’Text’>
      <Property title=’Email Address’/>
      <Property size=’60’/>
      <Property maxLength=’128’/>
   </Display>
 ...
</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></Disable>

Example


<Field name=’waveset id’>
   <Display class=’Text’>
      <Property title=’accountId’>
   </Display>
   <Disable>
      <eq><ref>userExists</ref><s>true</s></eq>
   </Disable>
</Field>

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.


Use caution when referencing fields with Disable rules. Otherwise, fields inside containers might be disabled.

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, simply do not assign a Display class to the field.

<Field name=’field A’/>

Calculating Field Values

Field values can be calculated from the values of other fields or any logical expression. For example, you can calculate the user’s full name from the first name, middle initial and last name.


<Field name=’global.fullname’>
   <Expansion>
      <concat>
         <ref>global.firstname</ref>
         <s> </s>
         <ref>global.middle</ref>
         <ref>global.lastname</ref>
         <s> </s>
      </concat>
   </Expansion>
</Field>

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:


Example 2–9 Setting global.email Default Values


<Field name=’global.email’>
   <Default>
      <and>
         <notnull><ref>global.firstname</ref></notnull>
         <notnull><ref>global.lastname</ref></notnull>
      </and>
         <concat>
         <downcase>
            <substr>
            <ref>global.firstname</ref>
            <i>0</i>
            <i>1</i>
            </substr>
         </downcase>
         <downcase>
            <substr>
            <ref>global.lastname</ref>
            <i>0</i>
            <i>6</i>
            </substr>
         </downcase>
         <s>@waveset.com</s>
      </concat>
   </Default>
</Field>

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.


<Field name=’P1’>
   <Display class=’Text’>
      <Property name=’title’ value=’Office Phone Number’/>
      <Property name=’size’ value=’3’/>
      <Property name=’maxLength’ value=’3’/>
   </Display>
</Field>
<Field name=’P2’>
   <Display class=’Text’>
      <Property name=’title’ value=’-’/>
      <Property name=’size’ value=’3’/>
      <Property name=’maxLength’ value=’3’/>
   </Display>
</Field>
<Field name=’P3’>
   <Display class=’Text’>
      <Property name=’title’ value=’-’/>
      <Property name=’size’ value=’4’/>
      <Property name=’maxLength’ value=’4’/>
   </Display>
</Field>
<Field name=’global.OfficePhone’>
   <Expansion>
      <concat>
         <ref>P1</ref><s>-</s>
         <ref>P2</ref><s>-</s>
         <ref>P3</ref>
      </concat>
   </Expansion>
</Field>

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.


<Field name=’P1’>
   <Display class=’Text’>
      <Property name=’title’ value=’Office Number’/>
      <Property name=’size’ value=’3’/>
      <Property name=’maxlength’ value=’3’/>
   </Display>
</Field>

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.


<defvar name=’lenOfficePhone’>
   <length><ref>Office Phone</ref></length>
</defvar>
<Field name=’P1’>
   <Display class=’Text’>
      <Property name=’title’ value=’Office Phone Number’/>
      <Property name=’size’ value=’3’/>
      <Property name=’maxLength’ value=’3’>
   </Display>
   <Derivation>
      <or>
      <cond><eq>
      <ref>lenOfficePhone</ref>
         <s>8</s></eq>
         <s> </s></eq>
      </cond>
      <cond><eq>
         <ref>lenOfficePhone</ref>
            <s>12</s></eq>
               <substr>
               <ref>Office Phone</ref>
               <i>0</i>
               <i>1</i>
               </substr>
      </cond>

      <cond><eq>
         <ref>lenOfficePhone</ref>
         <s>14</s></eq>
            <substr>
               <ref>Office Phone</ref>
               <i>0</i>
               <i>1</i>
            </substr>
      </cond>
      </or>
   </Derivation>
</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

<Field>
   <Display class=’Button’>
      <Property name=’label’ value=’Recalculate’/>
      <Property name=’command’ value=’Recalculate’/>
   </Display>
</Field>

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.

Example

<Field name=’Region’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Geographic Region’/>
      <Property name=’allowedvalues’ value=’North, South,
Central, Midwest’./>
<Property name=’nullValue’ value=’Select a region’/>
   </Display>
</Field>

Guidelines for Structuring a Form

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

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:

ProcedureTo Perform Optimizing Expressions

  1. Write a Java class that performs the database access.

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

  3. 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:

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:


<Field name=’jobGrade’>
   <Default>
      <invoke name=’getJobGrade’ class=’com.waveset.custom.DatabaseAccessor’>
         <ref>waveset.accountId</ref>
      </invoke>
   </Default>
</Field>
     </Derivation>

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.

ProcedureTo Define a Hidden Form Field

  1. Select Hidden from the Display Class menu.

  2. 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:


    <Field name=’testHiddenFieldList’ >
       <Display class=’Hidden’/ >
       <Derivation>
         <invoke name=’toString’>
           <List>
             <String>aaaa</String> <String>bbbb</String>
           </List>
         </invoke>
       </Derivation>
    </Field>

Referencing the Hidden Attribute

Once you have defined a hidden attribute, you can reference it in other expressions, such as:

<Field name=’secureKey’>
   <Disable><lt><ref>jobGrade</ref><i>10</i></lt></Disable>
     ...
</Field>

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 in the User Form

To enable manual linking, you must

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:

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:

<Attribute name=’secretAttributes’>
   <List>
     <String>email</String>
     <String>myAttribute</String>
   </List>
</Attribute>

Calling Resource Methods from Forms

You can invoke methods on a resource from a form by using the invoke method.

The invoke method is called by specifying the class name and name of the method. Arguments can also be passed to the method within the invoke tags as shown in the following example.


<Default>
   <block>
      <defvar name=’vmsResName’>
         <index i=’0’>
         <ref>accountInfo.accounts[type=vms].name</ref>
         </index>
      <defvar>
         <invoke name=’callResourceMethod’class=’com.waveset.ui.FormUtil’>
            <ref>display.session</ref>
            <ref>vmsResName</ref>
         <null/>
         </invoke>
</Default>

From the Form Element dialog for the field

ProcedureTo Call Resource Methods from a Form

  1. Select Javascript from the Display Class menu.

  2. Click OK.

Referencing a Form from Another Form

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

Use the <FormRef> element to include another form from within an external form. The following example calls the form named MissingFields.

<FormRef name=’MissingFields’/>
   <FieldRef name=’AuthenticationAnswers’/>
   <FieldRef name=’AccountInformation’/>
   <Field name=’waveset.backgroundSave’>
      <Display class=’Hidden’/>
   </Field>

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:


<Include>
   <ObjectRef type=’UserForm’
      id=’#ID#04F5F14E01889DFE:2E5C94:F131DD723D:-7FE4’
      name=’Password Library’/>
   <ObjectRef type=’UserForm’
      id=’#ID#04F5F14E01889DFE:2E5C94:F131DD723D:-7FE3’
      name=’Account Summary Library’/>
   <ObjectRef type=’UserForm’
      id=’#ID#UserForm:UserFormLibrary’/>
   <ObjectRef type=’UserForm’ name=’Global Attributes’/>
</Include>

In the following example, 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.


<Field name=’global.fullname’ hidden=’true’>
    <Expansion>
      <cond>
        <and>
          <ref>global.firstname</ref>
          <ref>global.lastname</ref>
        </and>
        <concat>
          <ref>global.firstname</ref>
             <s> </s>
          <ref>global.lastname</ref>
        </concat>
      </cond>
    </Expansion>
</Field>

In the following example, the <FieldRef> element identifies the name of the attribute you want to reference.


<Field>
    <Disable>
       <isnull>
          <ref>waveset.id</ref>
       </isnull>
    </Disable>
    <FieldRef name=’DynamicChangePasswordFields’/>
</Field>

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.

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:

The HTML components described in this task-oriented section are listed in alphabetical order in Chapter 7, HTML Display Components.

Working with Display Elements

The display elements you will most modify or add to an Identity Manager form are buttons, fields, and text entry boxes. Other display elements include tables and section headers.

Any display element that does not have a specified Display class will be hidden.

Buttons

To create a typical push button, use the <Button> component.

To align multiple buttons in a horizontal row, use the <ButtonRow> component.

<Field>
   <Display class=’Button’>
      <Property name=’location’ value=’true’/>
      <Property name=’label’ value=’Cancel’/>
      <Property name=’command’ value=’Cancel’/>
   </Display>
</Field>

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.

ProcedureTo Change Default Button Names

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


    <Form name=’Anonymous User Menu’>
    
       to
    
    <Form name=’Anonymous User Menu’ noDefaultButtons=true>

    At the bottom of the form, add the following fields for the Save and Cancel buttons, and change the labels as desired:


    <Field>
       <Display class=’Button’>
          <Property name=’label’ value=’Submit’/>
          <Property name=’name’ value=’submitButton’/>
          <Property name=’value’ value=’true’/>
          <Property name=’command’ value=’Save’/>
       </Display>
    </Field>
    <Field>
       <Display class=’Button’>
          <Property name=’label’ value=’Cancel’/>
          <Property name=’command’ value=’Cancel’/>
          <Property name=’location’ value=’true’/>
       </Display>
    </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.

Aligning Buttons with <ButtonRow> Element

To align multiple buttons in a row, use the ButtonRow element.


<Field name=’OrganizeButtons’>
   <Display class=’ButtonRow’>
      <Property name=’title’ value=’Choose a Button’/>
   </Display>
<Field name=’ChangePassword’>
   <Display class=’Button’>
      <Property name=’label’ value=’Change Password’/>
      <Property name=’value’ value=’Recalculate’/>
   </Display>
</Field>
<Field name=’ResetPassword’>
   <Display class=’Button’>
      <Property name=’label’ value=’Reset Password’/>
      <Property name=’value’ value=’Recalculate’/>
   </Display>
</Field>

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.

<Display class=’Text’>
   <Property name=’title’ value=’Zip Code’/>
   <Property name=’size’ value=’10’/>
   <Property name=’maxLength’ value=’10’/>
   <Property name=’required’ value=’true’/>
</Display>

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:

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:


<Field name=’SelectionTable’>
   <Display class=’SimpleTable’>
      <Property name=’columns’>
         <List>
            <String>Account</String>
            <String>Description</String>
         </List>
      </Property>
   </Display>
   <Field name=’accounts[LDAP].selected’>
      <Display class=’Checkbox’>
         <Property name=’label’ value=’LDAP’/>
      </Display>

   </Field>
   <Field>
      <Display class=’Label’>
         <Property name=’text’ value=’Primary Corporate LDAP Server’/>
      </Display>
   </Field>
   <Field name=’accounts[W2K].selected’>
      <Display class=’Checkbox’>
         <Property name=’label’ value=’Windows 2000’/>
      </Display>
   </Field>
   <Field>
      <Display class=’Label’>
      <Property name=’text’ value=’Primary Windows 2000 Server’/>
      </Display>
   </Field>

</Field>

Grouping Components

To group multiple components on a form to hide or disable them, use the <SimpleTable> container as shown in the following example.


Example 2–10 Grouping Components for a Form


<Field>
   <Disable>
      <not>
         <contains>
            <ref>accountInfo.typeNames</ref>
            <s>Windows Active Directory</s>
         </contains>
      </not>
   </Disable>
   <Field name=’accounts[AD].HomeDirectory’>
      <Display class=’Text’>
         <Property name=’title’ value=’Home Directory’>
      </Display>
   </Field>
</Field>

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 

<CheckBox>

See the section titled Creating a Checkbox.

Multiple-option list in which users can select only one option 

<RadioButton>

See the section titled Creating a Radio Button.

Multiple-option list (with many options) in which users can select only one option 

<Select>

See the section titled Creating a Single-Selection List.

Multiple-option list in which multiple options can be selected simultaneously 

<MultiSelect>

See the section titled Creating a Multiselection List.

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 1

<Field name=’accounts[LDAP].selected’>
   <Display class=’Checkbox’>
      <Property name=’label’ value=’LDAP’/>
   </Display>
</Field>

Example 2

<Field name=’global.Password.Expired’>
   <Display class=’CheckBox’>
      <Property name=’title’ value=’User must change password at
      next login’/>
      <Property name=’alignment’ value=’left’/>
   </Display>
</Field>

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.


<Field name=’global.EmployeeType’>
   <Display class=’Radio’>
      <Property name=’title’ value=’EmployeeType’/>
      <Property name=’labels’ value=’Employee, Contractor, Temporary, Part Time’/>
      <Property name=’required’ value=’true’/>
   </Display>
</Field>

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.


<Field name=’global.title’>
   <Display class=’Select’>
      <Property name=’title’ value=’Title’/>
      <Property name=’allowedValues’>
         <List>
         <String>Staff</String>
         <String>Manager</String>
         <String>Director</String>
         <String>VP</String>
         </List>
      </Property>
   </Display>
</Field>

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.


<Field name=’waveset.roles’>
   <Display class=’MultiSelect’ action=’true’>
      <Property name=’title’ value=’Roles’/>
      <Property name=’availableTitle’ value=’Available Roles’/>
      <Property name=’selectedTitle’ value=’Current Roles’/>
      <Property name=’allowedValues’>
            <invoke name=’getObjectNames’ class=’com.waveset.ui.FormUtil’>

               <ref>display.session</ref>
               <s>Role</s>
               <ref>waveset.original.roles</ref>
            </invoke>
      </Property>
   </Display>
</Field>

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:


Example 2–11 Changing Values for Select Lists Using the valueMap property


<Field name=’waveset.organization’>
<Display class=’Select’>
<Property name=’title’ value=’Add Account’/>
<Property name=’nullLabel’ value=’Select...’/>
<Property name=’valueMap’>
<list>
<s>Top</s>
<s>Top Level</s>
<s>Top:OrgB</s>
<s>Ted’s Organization</s>
<s>Top:OrgC</s>
<s>Super Secret Org</s>
</list>
</Property>
</Display>
</Field>

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:

See the section titled Representing Lists in XML Object Language and XPRESS for a discussion of the advantages to using XML Object language rather than XPRESS for certain tasks.

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.

<Field name=’department’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Department’/>
      <Property name=’allowedValues’>
         <List>
         <String>Accounting</String>
         <String>Human Resources</String>
         <String>Sales</String>
         <String>Engineering</String>
         </List>
      </Property>
   </Display>
</Field>

Dynamically Populating a Multiselection List of Groups

Multiselection lists typically contain two parts:

Adding a Multiselection List of Groups

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


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.


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 following example is interspersed with descriptive text.


<defvar name=’titleList’>
  <list>
    <s>Manager</s>
    <s>Accountant</s>
    <s>Programmer</s>
    <s>Assistant</s>
    <s>Travel Agent</s>
    <s>Other</s>
  </list>
</defvar>

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.



<Field name=’Title’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Title’/>
      <Property name=’allowedValues’>
      <Property name=’nullLabel’ value=’Select …"/>
         <expression>
           <ref>titleList</ref>
         </expression>
      </Property>
   </Display>
   <Derivation>
      <cond>
         <isnull><ref>global.Title</ref></isnull>
         <null/>
      <cond>
         <eq>
            <contains>
               <ref>titleList</ref>
               <ref>global.Title</ref>
            </contains>
            <i>1</i>
         </eq>
         <ref>global.Title</ref>
            <s>Other</s>
      </cond>
      </cond>
   </Derivation>
</Field>

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.


<Field name=’otherTitle’>
    <Display class=’Text’>
      <Property name=’title’ value=’Other Title’/>
      <Property name=’rowHold’ value=’true’/>
      <Property name=’noWrap’ value=’true’/>
      <Property name=’size’ value=’15’/>
      <Property name=’maxLength’ value=’25’/>
    </Display>
    <Disable>
      <neq>
        <ref>Title</ref>
        <s>Other</s>
      </neq>
    </Disable>
    <Derivation>
      <cond>
        <eq>
          <ref>Title</ref>
          <s>Other</s>
        </eq>
        <ref>global.Title</ref>
      </cond>
    </Derivation>
</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.


<Field name=’Title’>
   <Expansion>
     <cond>
       <eq>
         <ref>global.fieldTitle</ref>
         <s>Other</s>
       </eq>
       <ref>otherTitle</ref>
       <ref>Title</ref>
     </cond>
   </Expansion>
</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:

Change Password Form (User Interface)

Administrator Interface Forms:

<Exclude> Property Format

The Exclude Form Property takes the following form:

<Configuration wstype=’UserForm’ ...
   <Extension>
     <Form noDefaultButtons=’true’>
  ...
  <Properties>

To include disabled resource accounts in the list of displayed accounts, remove the disabled attribute condition from the list.


</Property>
<Property name=’Exclude’>
  <list>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>disabled</s>
       <s>equals</s>
    </new>
  </list>
 </Property>
 </Properties>
 ...
</Form>
</Extension>
</Configuration>

Valid View Attributes

The list of valid attribute names are those exposed by the views that are associated with each Form listed above for each instance of a currentResourceAccounts object. Valid attributes include:

Example: Excluding an LDAP Resource Type from a List of Resource Accounts

To exclude from the list of any given form all resource accounts of type LDAP that are not directly assigned, set the Exclude property as follows:


<Property name=’Exclude’>
 <list>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>type</s>
       <s>equals</s>
       <s>LDAP</s>
       <s>LDAP</s>
    </new>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>directlyAssigned</s>
       <s>equals</s>
       <s>false</s>
    </new>
 </list>
</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.


<Field name=’waveset.organization’>
   <Display class=’Select’>
      <Property name=’title’ value=’Organization’/>
      <Property name=’autoSelect’ value=’true’/>
      <Property name=’allowedValues’>
            <expression>
            <invoke class=’com.waveset.ui.FormUtil’
               name=’getOrganizationsWithPrefixes’>
               <ref>:display.session</ref>
            </invoke>
            </expression>
         </Property>
   </Display>
</Field>

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.

<Field>
   <Display class=’Label’>
      <Property name=’text’ value=’Primary Corporate LDAP
         Server’/>
   </Display>
</Field>

The value attribute is always a string.

Working with Other Display Elements

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

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.

<Field>
   <Display class=’SectionHead’>
      <Property name=’title’ value =’Calculated Fields’/>
   </Display>
</Field>

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.

Table 2–14 Expiration Date Formats

Expiration Date Field 

Format  

AIX 

MMddHHmmyy 

HPUX 

MM/dd/yy 

Solaris 

MM/dd/yyyy 

 <Field name=’aix_account_expire’>
    <Display class=’DatePicker’>
      <Property name=’title’ value=’Set Password Expiration Date’/>
   </Display>
 </Field>

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.


<Field name=’accounts[AIX].aix_expires’>
    <Display class=’Text’>
       <Property name=’title’ value=’Current Password Expiration Date’/>
       <Property name=’noNewRow’ value=’true’/>
       <Property name=’readOnly’ value=’true’/>
       <Property name=’size’ value=’10’/>
    </Display>
    <Expansion>
       <cond>
         <notnull>
           <ref>aix_account_expire</ref>
         </notnull>
         <invoke name=’dateToString’ class=’com.waveset.util.Util’>
       <!-- First argument to dateToString method is a date object -->
           <ref>aix_account_expire</ref>
       <!-- Second argument is the format you want the converted date/string in -->
           <s>MMddHHmmyy</s>
         </invoke>
         <ref>accounts[AIX].aix_expires</ref>
       </cond>
      </Expansion>
</Field>

Adding a Back Link

You can add a component that behaves the same as the browser Back button. This component permits you to add a back link anywhere on the form.

<Field name=’back’>
   <Display class=’BackLink’>
      <Property name=’title’ value=’Back’/>
      <Property name=’value’ value=’previous page’/>
   </Display>
</Field>

Positioning Components on a Form

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

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

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:

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:

<Property name='RequiresChallenge'>
   <List>
     <String>password</String>
     <String>email</String>
     <String>fullname</String>
   </List>
</Property>

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.

Setting the RequiresChallenge Property for Change Password and Reset Password Forms

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:

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

<Derivation>
   <or>
      <ref>accounts[AD].fullname</ref>
      <ref>accounts[LDAP].fullname</ref>
   </or>
</Derivation>

Example 2;

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.


<Field name=’location’ prompt=’Location’>
   <Display class=’Text’/>
      <Derivation>
      <switch>
            <ref>accounts[Oracle].locCode</ref>
            <case>
               <s>AUS</s>
               <s>Austin</s>
            </case>
            <case>
               <s>HOU</s>
               <s>Houston</s>
            </case>
            <case>
               <s>DAL</s>
               <s>Dallas</s>
            </case>
            <case default=’true’>
               <s>unknown</s>
            </case>
      </switch>
      </Derivation>
</Field>

Examples of <Expansion> Statement

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

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.


<Field name=’global.lastname’>
   <Display class=’Text’>
       <Property name=’title’ value=’Last Name’/>
       <Property name=’size’ value=’32’/>
       <Property name=’maxLength’ value=’128’/>
       <Property name=’noNewRow’ value=’true’/>
       <Property name=’required’>
         <Boolean>false</Boolean>
       </Property>
   </Display>
        <Expansion>
          <block>
            <defvar name=’lname’>
              <downcase>
                <ref>global.lastname</ref>
              </downcase>
            </defvar>
            <defvar name=’nlength’>
              <sub>
                <length>
                  <ref>global.lastname</ref>
                </length>
                <s>1</s>
              </sub>
            </defvar>
            <concat>
              <substr>
                <upcase>
                  <ref>global.lastname</ref>
                </upcase>
                <s>0</s>
                <s>1</s>
              </substr>
              <substr>
                <ref>lname</ref>
                <s>1</s>
                <ref>nlength</ref>
              </substr>
            </concat>
          </block>
</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.

<Field name=’accounts[Oracle].locCode’>
   <Expansion>
      <switch>
         <ref>location</ref>
            <case>
               <s>Austin</s>
               <s>AUS</s>
            </case>
            <case>
               <s>Houston</s>
               <s>HOU</s>
            </case>
            <case>
               <s>Dallas</s>
               <s>DAL</s>
            </case>
      </switch>
   </Expansion>
</Field>

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.

<Field name=’age’>
   <Validation>
     <cond>
       <lt>
         <ref>age</ref>
         <i>0</i>
       </lt>
       <s>Age may not be less than zero.</s>
     </cond>
   </Validation>
</Field>
 

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:

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.

Table 2–17 Supported Object Types

Resource 

Supported Object Types 

AIX 

account, Group 

ACF2 

account 

ClearTrust 

account, Group, group, Administrator_Groups, Applications, Entitlements, User_Properties 

Entrust 

Group, Role 

GroupWise 

account, Distribution Lists, PostOffices 

HP-UX 

account, Group, shell 

LDAP 

account, Group 

Oracle 

USERS, ROLE, PROFILE 

NDS 

account, Group 

PeopleSoft 

account 

RACF 

account, Group 

SAP 

account, table, profiles, activitygroups 

SecurID 

UnassignedTokens 

SP2 

Nodes 

Solaris 

account, Group, shell 

TopSecret 

account 

VMS 

account 

Windows Active Directory 

account, Group 

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:

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

<invoke name=’listResourceObjects’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>Group</s>
   <s>AD</s>
   <Map>
     // This allows you to return a list of groups only in
        and below the specified container/organizational unit
      <MapEntry key=’container’ 
                value=’LDAP://hostX.domainX.com/cn=Users,dc=domainX,dc=com’/>
   </Map>
   <s>false</s>
</invoke>

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.

The following code first defines the base context to append to users.

<Field name=’baseMemberContextContractor’>
   <Default>
      <s>ou=Contractors,dc=example,dc=com</s>
   </Default>
</Field>
<Field name=’baseMemberContextEmployee’>
   <Default>
      <s>ou=Employees,dc=example,dc=com</s>
   </Default>
</Field>
 

The user of this form enters data in the following field. This is a likely place for providing a dynamically generated list of user IDs.

 <Field name=’userIds’>
   <Display class=’TextArea’>
      <Property name=’title’ value=’UserIds’/>
   </Display>
</Field>

The following hidden field includes logic that calculates values.

<Field name=’Members’>
   <Expansion>
      <switch>
      // Look at the role assigned to the users
      <ref>waveset.role</ref>
      <case>
      // If user has "Contractor Role" then build DN like this:
      // ex: CN=jsmith,ou=Contractors,dc=example,dc=com
         <s>Contractor Role</s>
         <invoke name=’buildDns’ class=’com.waveset.ui.FormUtil’>
            <ref>userId</ref>
            <ref>baseMemberContextContractor</ref>
         </invoke>
      </case>
      <case>
// Otherwise, if user has "Employee Role", then build DN like this:
         // ex: CN=jdoe,ou=Employees,dc=example,dc=com
         s>Employee Role</s>
         <invoke name=’buildDns’ class=’com.waveset.ui.FormUtil’>
            <ref>userId</ref>
            <ref>baseMemberContextEmployee</ref>
         </invoke>
         </case>
      </switch>
   </Expansion>
</Field>

Building a Single DN String

You can call the buildDn method to populate a list or text area with a single DN. Example:

<invoke name=’buildDn’ class=’com.waveset.ui.FormUtil’>
   <s>jdoe</s>
   <s>dc=example,dc=com</s>
</invoke>

This example returns CN=jdoe,dc=example,dc=com.

Getting a List of Unassigned Resources

To retrieve a list of all resources to which the user ID could potentially have permission to view but is currently unassigned, call the getUnassignedResources method.

The <ref> statements identify the view attribute that contains information about the specified user. Example:

<invoke name=’getUnassignedResources’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <ref>waveset.role</ref>
   <ref>waveset.original.resources</ref>
</invoke>

Retrieving a List of Accessible Object Types

To get a list of object types that the session owner currently has access to, use the getObjectNames method.

You can request the following object types:

For a complete list of object types, see the List Objects option on the Debug page. Example:

<invoke name=’getObjectNames’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>UserForm</s>
</invoke>

Retrieving a List of Object Types Accessible by the Session Owner

To get a list of object names for which the session owner has access, use the getObjectNames method. Example:

<invoke name=’getObjectNames’ class=’com.waveset.ui.FormUtil’>
  <ref>:display.session</ref>
</invoke>

Getting a List of Organizations with Prefixes

To get a list of organizations with prefixes (for example, TOP, TOP:IT, TOP:HR), use the getOrganizationsWithPrefixes method. Example:

<invoke name=’getOrganizationsWithPrefixes’  class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
</invoke>

Getting a List of Organizations without Prefixes

To retrieve a list of organizations without prefixes (for example, TOP, TOP, TOP), use the getOrganizations method. Example:

<invoke name=’getOrganizations’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
</invoke>

Getting a List of Organizations Display Names with Prefixes

To retrieve a list of organization display names with prefixes, use the getOrganizationsDisplayNamesWithPrefixes method.

<invoke name=’getOrganizationsDisplayNamesWithPrefixes’  class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
</invoke>

Retrieving a List of Applications Unassigned to the User

To get a list of applications to which the user is not currently assigned, use the getUnassignedApplication method. Example:

<invoke name=’getUnassignedApplications’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <ref>waveset.roles</ref>
   <ref>waveset.original.applications</ref>
</invoke>

Constructing Hash Maps

The listResourceObjects and callResourceMethods methods accept hash maps. You can construct hash maps with the <Map> element.

In the following example, the <Map> element builds a static map that never changes.

  <Map>
     <MapEntry name=’key1’ value=’value1’/>
     <MapEntry name=’key2’ value=’value2’/>
  </Map>

You can also construct maps with an XPRESS expression through the use of the <map> element. You can use the <map> element to dynamically build a map whose contents are defined by other expressions.

For information on using the XPRESS language to construct a map, see Chapter 5, XPRESS Language

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

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:

For a comprehensive discussion of rules, see Chapter 4, Working with Rules.

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.

For a comprehensive discussion of XPRESS features, see Chapter 5, XPRESS Language

Why Use XPRESS?

Expressions are used primarily for the following Identity Manager tasks:

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:

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.

<Field name=’waveset.role’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Role’/>
      <Property name=’nullLabel’ value=’None’/>
      <Property name=’allowedValues’>
         <expression>
            <invoke class=’com.waveset.ui.FormUtil’ name=’getRoles’>
            <ref>:display.session</ref>
        <ref>waveset.original.role</ref>
            </invoke>
         </expression>
      </Property>
   </Display>
 </Field>

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:

Procedure To Customize the Resource Schema Map

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

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

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

  3. Save your changes, and restart your application server.

Adding Guidance Help to Your Form

Identity Manager supplies two types of online help:

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

For example:

<Attribute name=’customMessageCatalog’ value= ’sampleCustomCatalog’ />

The following sample sets custom guidance help for a component called _FM_DELEGATEWORKITEMSFORM_SELECT_WORKITEM_TYPE.

<Waveset>
   <Configuration name="sampleCustomCatalog">
      <Extension>
         <CustomCatalog id="defaultCustomCatalog" enabled="true">
            <MessageSet language="en" country="US">
            <Msg id="_FM_DELEGATEWORKITEMSFORM_SELECT_WORKITEM_TYPE">
                   Select Work Item Type</Msg>
            <Msg id="_FM_DELEGATEWORKITEMSFORM_SELECT_WORKITEM_TYPE_HELP>
                   Type of Work Item: Select work item type from the list.</Msg>
            </MessageSet>
         </CustomCatalog>
      </Extension>
   </Configuration>
</Waveset>

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.

<Waveset>
   <Configuration name="sampleCustomCatalog">
      <Extension>
         <CustomCatalog id="defaultCustomCatalog" enabled="true">
            <MessageSet language="en" country="US">
               <Msg id="UI_END_USER_VERSION"></Msg>
               <Msg id="UI_VERSION"></Msg>
            </MessageSet>
         </CustomCatalog>
      </Extension>
   </Configuration>
</Waveset>

Other Form-Related Tasks

Miscellaneous form-related tasks include:

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.

<invoke class = ’com.waveset.ui.FormUtil’
   name = ’listResourceObjects’>
</invoke>

where the name field identifies the name of the method.

For examples on using these methods within forms, see the section titled Using Hidden Components.

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).

Example:

<invoke name=’testObject’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>User:</s>
   <s>jdoe</s>
</invoke>

The testObject method returns true on successful find of an object. Otherwise, this method returns null.

To test if a user exists, use the testUser method. The <s> element identifies the name of the user object to find. Example:

<invoke name=’testUser’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>jdoe</s>
</invoke>

This method returns true on successful find. Otherwise, this method returns null.

Inserting Alert Messages into XPRESS Forms

You can insert WARNING), error (ERROR), or informational (OK) alert messages into an XPRESS form.


Note –

Although this example illustrates how to insert a Warning ErrorMessage object into a form, you can assign a different severity level.


ProcedureTo Insert an Alert Message

  1. Use the Identity Manager IDE to open the form to which you want to add the warning.

  2. Add the <Property name=’messages’> to the main EditForm or HtmlPage display class.

  3. Add the <defvar name=’msgList’> code block from the following sample code.

  4. Substitute the message key that identifies the message text to be displayed in the Alert box in the code sample string:

    <message name=’UI_USER_REQUESTS_ACCOUNTID_NOT_FOUND_ALERT_VALUE >

  5. Save and close the file.


    <Display class=’EditForm’>
       <Property name=’componentTableWidth’ value=’100%’/>
       <Property name=’rowPolarity’ value=’false’/>
       <Property name=’requiredMarkerLocation’ value=’left’/>
       <Property name=’messages’>
         <ref>msgList</ref>
       </Property>
    </Display>
    <defvar name=’msgList’>
      <cond>
        <and>
          <notnull>
            <ref>username</ref>
          </notnull>
          <isnull>
            <ref>userview</ref>
          </isnull>
        </and>
        <list>
          <new class=’com.waveset.msgcat.ErrorMessage’>
            <invoke class=’com.waveset.msgcat.Severity’ name=’fromString’>
               <s>warning</s>
            </invoke>
            <message name=’UI_USER_REQUESTS_ACCOUNTID_NOT_FOUND_ALERT_VALUE’>
              <ref>username</ref>
            </message>
          </new>
        </list>
      </cond>
    </defvar>

    To display a severity level other than warning, replace the <s>warning</s> in the preceding example with either of the these two values:

    • error -- Causes Identity Manager to render an InlineAlert with a red “error” icon.

    • ok -- Results in an InlineAlert with a blue informational icon for messages that can indicate either success or another non-critical message.

    Identity Manager renders this as an InlineAlert with a warning icon


    <invoke class=’com.waveset.msgcat.Severity’ name=’fromString’>
    <s>warning</s>
    </invoke>

    where warning can also be error or ok.

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:

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. ,

ProcedureTo Create a Wizard Form

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

  2. Set the noCancel property to true.

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

    The following example provides comments for guidance purposes:


    <Form>
       <Display class="HtmlPage"/> ----- If not set, causes indentation and color problems
       <Field name=’MainTabs’> -- Name of the top container that wraps the tab pages
          <Display class=’TabPanel’/> -- Display class for the top container: 
                                         either TabPanel or WizardPanel
       <Field name=’Identity’> -- Label of the Tab
          <Display class=’EditForm’> -- Each “page” must be an Edit Form
             <Property name=’helpKey’ value=’Identity and Password Fields’/>
          </Display>
       <Field name=’waveset.accountId’>
          <Display class=’Text’>
             <Property name=’title’ value=’_FM_ACCOUNT_ID’/>
          </Display>
    <Disable> <ref>waveset.id</ref> </Disable>
    
       </Field>
       </Field>
    
    </Field>

Tips and Workarounds

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:

Identity Manager provides scalable versions of the default Edit and Create User forms.

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


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

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.

ProcedureStep 1: Import the Form

  1. From the Identity Manager menu bar, select Configure > Import Exchange File.

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

  3. 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:

ProcedureAssign Scalable User Form as the Default User Form

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

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

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

ProcedureAssign Scalable User Form per Administrator

  1. From the menu bar, select Accounts > Edit User.

  2. 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

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

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

  5. 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. 

Resource Table User Form Library 

Contains primary fields for the Resource Table User form. Includes bread crumb and navigation fields. 

Resource Table Account Info Form 

Contains Fields for account information section of Resource Table form. 

Resource Table Rule Library 

Contains the rule library for retrieving, counting, analyzing a user’s resources. This is mostly used by the User Form Library and to build table data on roles and resources. 

Resource Table Utility Library 

Contains the rules used during the selection process on Resource Table Form, for example these rules retrieve resources per role or per type. 

Installing Resource Table User form involves two steps: importing the form, and changing the form mapping.

ProcedureStep 1: Import the Form

  1. From the Identity Manager menu bar, select Configure > Import Exchange File.

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

ProcedureStep 2: Change Form Mapping

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

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

  3. 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:

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.

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.

Customizing Tabbed User Form: Moving Password Fields to the Attributes Area

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

By default, Identity Manager displays password policy information on the Accounts > Identity tab, as shown below.

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:

ProcedureTo Move the Password Fields from Their Default Position

  1. Set the manualPasswordSynchronization checkout property

  2. Add Field and FieldLoop components to the Tabbed User form

  3. 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:

<Form>
   <Properties>
     <Property name=’manualPasswordSynchronization’ value=’true’/>
...
   </Properties>
...
</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:


<Field name=’viewOptions.CallViewValidators’>
  <Display class=’Hidden’/>
    <Expansion>
        <s>false</s>
    </Expansion>
</Field>

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.


<Field name=’savePasswordHistory’>
   <Default>
      <Boolean>true</Boolean>
   </Default>
</Field>

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.


<Activity id=’5’ name=’SetPasswordView’>
   <Action id=’0’>
     <expression>
          <set name=’PasswordView.resourceAccounts.password’>
             <ref>password</ref>
          </set>
     </expression>
   </Action>
<!-- Add action here -->
   <Action id=’1’>
    <expression>
         <set name=’PasswordView.savePasswordHistory’>
             <Boolean>true</Boolean>
        </set>
    </expression>
   </Action>
   <!-- end -->
   <Action id=’2’>
     <expression>
       <dolist name=’account’>
        <ref>PasswordView.resourceAccounts.currentResourceAccounts</ref>

Option 2: Changing a System Configuration Object Setting

Alternatively, you can edit the relevant System Configuration object setting. You can configure the savePasswordHistory option through the Login application.

ProcedureTo Modify a System Configuration Object Setting

  1. In the System Configuration object, locate this path:

    security.admin.changePassword.[login interface]

  2. Switch the values for savePasswordHistory for the appropriate interfaces from false to true (see example below). By default, these values are false.


     <Attribute name=’security’>
       <Object>
         <Attribute name=’admin’>
           <Object>
              <Attribute name=’changePassword’>
                 <Object>
                    <Attribute name=’Administrator Interface’>
                       <Object>
                          <Attribute name=’savePasswordHistory’>
                             <Boolean>false</Boolean>
                          </Attribute>
                       </Object>
                    </Attribute>
                    <Attribute name=’Command Line Interface’>
                       <Object>
                          <Attribute name=’savePasswordHistory’>
                             <Boolean>false</Boolean>
                          </Attribute>
                       </Object>
                    </Attribute>
                    <Attribute name=’IVR Interface’>
                       <Object>
                          <Attribute name=’savePasswordHistory’>
                             <Boolean>false</Boolean>
                          </Attribute>
                       </Object>
                    </Attribute>
                    <Attribute name=’SOAP Interface’>
                       <Object>
                          <Attribute name=’savePasswordHistory’>
                             <Boolean>false</Boolean>
                          </Attribute>
                      </Object>
                    </Attribute>
                    <Attribute name=’User Interface’>
                      <Object>
                          <Attribute name=’savePasswordHistory’>
                             <Boolean>false</Boolean>
                          </Attribute>
                      </Object>
                    </Attribute>
                 </Object>
              </Attribute>
           </Object>
         </Attribute>
         <Attribute name=’authn’>
            <Object> ..

    To permit password history recordings through the SPML interface, you must set the following in the system configuration object:

    security.admin.changePassword.Command Line Interface

Testing Your Customized Form

You can gather information about edited forms before implementing them in your runtime environment through the following ways:

Turning On and Off Error Logging

The Identity Manager error logging utility reports to standard output any problems with the syntax of form expressions. Once XPRESS tracing is turned on, you can limit log messages to XPRESS statements for a subset of the form with the <block> tag. To obtain more information about the processing of XPRESS statements, a configuration option in the waveset.properties file, xpress.trace, can be set to true. When this option is set to true, all evaluations of XPRESS statements will generate trace messages to the console. This can be used to debug statements that are evaluated inside a running application whose code cannot be changed to enable tracing through the XPRESS API.

You can turn on XPRESS tracing for all XPRESS fields through either the command line or the Identity Manager Administrator Interface. Turning on tracing this way affects all fields. To limit log messages to a subset of the form, use the <block> tag set to limit error tracing to only code within the <block></block> tags.

Procedure To Turn on Error Logging from the Command Line

  1. Open the config/waveset.properties file for editing.

  2. Search on the line xpress.trace=false.

  3. Change the false value to true.

  4. Save the file.

  5. Restart the application server.

    Alternatively, you can use the Identity Manager Administrator Interface to turn on and off error logging.

  6. Login into Identity Manager as Configurator.

  7. Select Debug to open the Debug page.

  8. From the Debug page, select Reload Properties.

    To turn tracing off for XPRESS, set the xpress.trace value to false, and reload the waveset.properties file.

Sample Forms and Form Fields

This section provides examples of the default forms that ship with the product. It also describes how to incorporate sample forms in your environment.


Note –

The versions of forms that ship with your version of Identity Manager may differ slightly from these samples.


User Form Library

A form can be used as a container for a collection of fields rather than being used in its entirety. Identity Manager supports this use of forms with an object called User Form Library, which contains complex fields related to granular resource selection, such as those used for changing passwords.

The following list summarizes each library associated with User Library.

User Library

The primary user form library. It includes the other libraries in this table and also defines the AuthenticationAnswers field for the display and editing of authentication question answers. 

Password Library

Fields related to password specification and synchronization. 

Account Summary Library

Fields that display read-only summary information about the accounts associated with a user. 

Account Link Library

Fields related to account linking, and multiple accounts per resource. 

User Security Library

Fields related to user security including capabilities, form assignment, and approval forwarding. 

User Form Library

This library contains only fields that are related to the Resource Accounts views which include:

The library primarily consists of tables that display information about the resource accounts associated with an Identity Manager user and allows them to be selected for various operations.

Using the Sample Forms Library

You can include the sample forms shipped with Identity Manager in any of the forms you are customizing through the use of the <FormRef> element.

Follow these general steps to add sample forms to your environment:

Step 1: Import the Rule

Step 2: Import the Form

Step 3: Create a New Form from the Default Form (Add Include References and Add the Form Reference)

Step 1: Import the Rule

Use the Identity Manager Administrator Interface to load the sample rules. :

ProcedureTo Load a Rule

  1. From the Identity Manager menu bar, select Configure > Import Exchange File.

  2. Enter the sample file name or click Browse to locate the file in the idm\sample\rules directory.

    Sample common rule file names are:

    • sample\rules\ListGroups.xml

    • sample\rules\NamingRules.xml

    • sample\rules\RegionalConstants.xml

    Sample resource rule file names are:

    • sample\rules\ADRules.xml

    • sample\rules\NDSRules.xml

    • sample\rules\NTRules.xml

    • sample\rules\OS400UserFormRules.xml

    • sample\rules\RACFUserFormRules.xml

    • sample\rules\TopSecretUserFormRules.xml

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

Step 2: Import the Form

Use the Identity Manager Administrator Interface to load the sample form.

ProcedureTo Import the Form

  1. From the Identity Manager menu bar, select Configure > Import Exchange File.

  2. Enter the sample file name or click Browse to locate the file in the idm\sample\forms directory. Sample form file names are:

    • sample\forms\ACF2UserForm.xml

    • sample\forms\ AIXUserForm.xml

    • sample\forms\HP-UXUserForm.xml

    • sample\forms\NDSUserForm.xml

    • sample\forms\OS400UserForm.xml

    • sample\forms\SecurIDUserForm.xml

    • sample\forms\SolarisUserForm.xml

    • sample\forms\TopSecretUserForm.xml

    • sample\forms\vitalStatform.xml

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

Step 3: Update the Tabbed User Form (Add Include References)

Add an include reference to the sample form from the Tabbed User Form or a main form you created.

ProcedureTo Update the User Form

  1. Copy the Tabbed User Form and rename it (for example, <CompanyName>tabbedUserForm).

  2. In your Web browser address line, type this URL, and then press Enter.

    http://ApplicationServerHost:Port/idm/debug

  3. After you authenticate, Identity Manager displays the System Settings page.

  4. Select the UserForm option from the Type list, and then click List Objects.

  5. Click Edit next to the <CompanyName>tabbedUserForm (or the main form you created).

  6. Change the includes area of the form to add each sample form, shown in the following example in bold text:


    <Include>
      <ObjectRef type=’UserForm’ id=’#ID#UserForm:UserformLibrary’ name=’UserForm Library’/>
      <ObjectRef type=’UserForm’ name=’UserFormName’/>
    <Include>

    Values for UserFormName can be:

    • ACF2 User Form

    • AIX User Form

    • HP-UX User Form

    • LDAP Active Sync User Form

    • Netegrity Siteminder Admin Form

    • Netegrity Siteminder LDAP User Form

    • Netegrity Siteminder ExampleTable User Form

    • NDS User Form

    • NT User Form

    • Open Networks User Form

    • OS400 User Form

    • Oracle ERP User Form

    • RACF User Form

    • RSA ClearTrust User Form

    • SecurID User Form

    • Skeleton Database Active Sync User Form

    • Solaris User Form

    • Tivoli Access Manager

    • Top Secret User Form

    • Global Attributes (vitalStatform.xml)

      Continue with the next section before saving the form.

Step 4: Update the Tabbed User Form (Add the Form)

Add a FormRef for each sample form to add it to the main form.

ProcedureTo Add a FormRef

  1. Add the following line for each sample form in an appropriate location in the main form:


    <FormRef name=’UserFormName’/>
  2. Remove the following line:


    <FormRef name=’MissingFields’/>
  3. Click Save to save form changes.

Compliance-Related Forms

Table 2–22 Compliance-Related Forms

Form Name  

General Purpose  

Access Approval List 

Display the list of attestation workitems 

Access Review Delete Confirmation 

Confirm the deletion of an access review 

Access Review Abort Confirmation 

Confirm the termination of an access review 

Access Review Dashboard 

Show the list of all access reviews 

Access Review Summary 

Show the details of a specific access review 

Access Scan Form 

Display or edit an access scan 

Access Scan List 

Show the list of all access scans 

Access Scan Delete Confirmation 

Confirm the deletion of an access scan 

UserEntitlementForm 

Display the contents of a UserEntitlement 

UserEntitlement Summary Form 

 

Violation Detail Form 

Show the details of a compliance violation 

Remediation List 

Show a list of remediation work items 

Audit Policy List Detailed 

Show a list of audit policies 

Audit Policy Delete Confirmation Form 

Confirm the deletion of an audit policy 

Conflict Violation Details Form 

Show the SOD violation matrix 

Compliance Violation Summary Form 

 

Using the FormUtil Methods

This section discusses high-level considerations and usage tips for this class of methods. The FormUtil methods are utilities used by forms when transforming a view. You can find specific information about each method in the FormUtil Javadoc.

For information on specific methods, see <distribution>\REF\javadoc, where <distribution> is your installation directory.

FormUtil Class Methods

The FormUtil class provides a collection of utility methods that are intended to be called from XPRESS expressions within form objects. The FormUtil methods are usually used within the valueMap property of Select and MultiSelect fields to constrain the list of possible values. Identity Manager provides additional methods to format string values such as dates and directory DNs.

Understanding Method Context

Any FormUtil method that needs to access the Identity Manager repository will need a context object.The Lighthouse context represents an authenticated session, which is subject to authorization checking to enforce visibility and action restrictions.

Fetching Context

Most FormUtil methods require that a LighthouseContext or Session object be passed as the first argument by referencing the view attribute display.session. Since forms are often used with a base context prefix, it is recommended that the display.session reference always be preceded with a colon (:display.session) to remove the base context prefix.

Invoking Methods

Use the following syntax to invoke the FormUtil methods from within a form:

<invoke class = ’com.waveset.ui.FormUtil’
   name = ’method_name’>
      <ref>:display.session</ref>
      <s>arg2</s>
</invoke>

where the name field identifies the name of the method.

Calling FormUtil Methods without Knowing the Context

You can use select without understanding which variable specifies the Lighthouse Context. This approach facilitates re-use of the method invocation.

<select>
   <ref>:display.session</ref>
   <ref>context</ref>
</select>

In a form, you would specify the context with <ref>:display.session</ref>. However, the same FormUtil call in a workflow would instead use <ref>context</ref>.

A third method for fetching context involves invoking a getLighthouseContext method using WF_CONTEXT object. Below we wrap all three techniques in a rule, which can be used later.


<rule name=’Get Context’>
<select>
   <ref>:display.session</ref>
   <ref>context</ref>
   <invoke name=’getLighthouseContext’>
      <ref>WF_CONTEXT</ref>
   </invoke>
</select>
</rule>

Best Practice

You can create a rule with a name such as Get Context that contains a simple <select> statement. You can then call that rule from any form or any workflow during an invocation of the desired FormUtil method, as shown in the following example:


<invoke name=’getObject’>
 <!-- typically, something like :display.session would go here. 
      But instead, call the handy rule -->
<rule name=’Get Context’/>
 <s>User</s
<s>SamUser</s>
</invoke>

That invocation could then be part of a greater utility rule that you can use in both forms and workflows.

Commonly Invoked Methods

The following table provides a brief introduction to the most commonly used FormUtil methods.

Method  

Description  

callResourceMethod 

Invokes the specified method on the resource by passing it the specified arguments. 

buildDn, buildDns 

Takes a name (or names) and the base context to append to the name. This method returns a string of fully qualified distinguished (DN) names. For example, passing in group1 and dc=example,dc=com returns the string cn=group1, dc=example, dc=com. 

checkStringQualityPolicy 

Checks the value of a designated string against string policy. 

controlsAtLeastOneOrganization 

Determines whether a currently authenticated user controls any of the organizations specified on a list of one or more organization (ObjectGroup) names. The supported list of organizations include those returned by listing all objects of type ObjectGroup. 

getObject 

Retrieves an object from the repository (subject to authorization). 

getObjectNames 

Returns a list of the names of objects of a given type to which the session owner (or currently logged-in user) has access. Additional parameters can be specified in the options map to control the list of names returned. 

This method is the preferred way for returning a list of names of objects rather than attempting session.getObjects(). This method first goes to the ObjectCache, then to the repository, if necessary, for searches.

getOrganizationsDisplayNames 

Returns a list of organization handles that the current administrator has access to. Forms that need select and multiselection lists of organizations should use this method. 

getResources 

Builds a list of the names of resources that match a particular resource attribute value (such as type=LDAP). If a current list is passed in, the lists are merged. 

getResourceObjects 

Returns a list of objects where each object contains a set of attributes including type, name, and ID (a DN, or fully qualified name) as well as any requested searchAttrsToGet value. The returned value is a List of GenericObjects. Each GenericObject can be accessed similar to how a Map is accessed. Invoking a get method on each object, which passes in the name of the attribute, returns the attribute value.

getRoles 

Returns a list of role names that the current administrator has access to. If a current value or current list is supplied, the role name or names on the list are added to the role names returned. 

getUnassignedApplications 

Builds a list of application names suitable for a user’s private applications. (A private application is an application that is directly assigned to a user.) This is the list of all accessible applications minus the names of the applications that are already assigned to the user through their role.

The resulting list is convenient for use in forms for assigning private applications. 

getSubordinates 

Retrieves a list of the specified managerial subordinates of a user. 

getUnassignedResources 

Build a list of resource names suitable for the private resources of a user. (A private resource is a resource that is directly assigned to a user.) This is the list of all accessible resources minus the names of the resources that are already assigned to the user through their role.

The resulting list is convenient for use in forms for assigning private resources. 

getUsers 

The first variant of this method returns all users. The second variant by default returns all users, but you can specify a map of options to further filter the list. 

listResourceIObjects 

Retrieves a list of resource objects of a specified type (for example, group). This method first attempts to get the list from the server’s resourceObjectListCache. If found, this list is returned.

If this list is not found, the method invokes the listResourceObjects method on each resource before merging, sorting, and removing duplicates on the resulting lists. Finally, it caches this new list in the server’s resourceObjectListCache for any subsequent requests for the same resource object type from the same resource(s).

This method runs as the currently authenticated administrator (for example, subject). Variants take a single resource ID or a subject string and an existing session.

This method has multiple variants that differ on whether: 

The method returns a single resource versus a resource list. 

The cache should be cleared. 

The method is sending a session ID (implemented when the user has already been authenticated) or a subject string (subjectString). Typically, you will use Session.

testObject 

Tests to see if a specified object exists, even if the subject is not authorized to view the object. When launching processes to create new users, use this method to prevent attempts to create duplicate objects by an administrator who cannot see the entire tree. 

testUser 

Tests to see if a specified user exists, even if the subject is not authorized to view the object. When launching processes to create new users, use this method to prevent attempts to create duplicate objects by an administrator who cannot see the entire tree. 

hasCapability, hasCapabilities 

Checks to see if the user has a specified capability or capabilities (String). This method checks for a capability that is assigned either directly or indirectly through AdminGroups and/or AdminRoles. Requires a session value.

Tips on FormUtil Usage

Some of the trickiest common implementation of the FormUtil methods involve retrieving objects, particularly using the following methods.

This section introduces basic hints for using these methods.

Using getObject to Fetch Objects from the Repository

The getObject method is the most commonly used method for retrieving an object from within the repository. When using this method, remember that you are fetching actual (Java) objects. To access attributes from that object, you must wrap the object in an invocation that calls the object’s getter methods. Because each object uses particular get operations, refer to the individual object’s Javadoc for more detail.

When working with the WSUser object, you can use the WSUser object’s toHashMap() method. This method converts the object into a GenericObject, which is equivalent to a Java HashMap, as shown in the following example:


<set name=’wsUserObj’>
   <invoke name=’getObject’>
<!-- typically, a value such as :display.session would go here;
instead, call the handy rule -->
       <rule name=’Get Context’/>
       <s>User</s.
       <s>SamUser</s>
   </invoke>
</set>
<set name=’wsGenericObj’>
   <invoke name=’toHashMap’>
   <ref>wsUserObj</ref>
   </invoke>
</set>

To retrieve the accountId from the WSUser object, use the following

<invoke name=’getAccountId’>
 <ref>wsUserObj</ref>
</invoke>

However, when you are working with a user, this method can become tedious. The same thing via the WSUser object now converted into a GenericObject:

<ref>wsGenericObj.waveset.accountId</ref>

Basically, GenericObjects, such as views, can be much easier to work with than the WSUser object. Consider checking out the view of the associated object when dealing directly with the object is cumbersome.


Note –

Some operations will result in the repository locking the underlying PersistentObject. Typically, methods that begin with the phrase “checkout” will lock the object, “checkin” will unlock it), and methods that being with “get” will not lock the object.


Using getResourceObject to Fetch Objects from a Resource

The getResourceObject operation returns the specified object from the specified resource as a GenericObject. See the Resource Reference for an explanation of which objects can be fetched and which attributes are supported in the list. This method results in a call to the corresponding resource adapter.

Using the getUnassigned* Methods

The getUnassigned* methods retrieve features that are not currently assigned to the provided user (through the lh context). These methods are handy when you must create a User form that offers the user to select, and thus request access to, a feature they currently do not have. For example:


<Field name=’waveset.resources’>
   <Display class=’MultiSelect’ action=’true’>
     <Property name=’title’ value=’_FM_PRIVATE_RESOURCES’/>
     <Property name=’availableTitle’ value=’_FM_AVAILABLE_RESOURCES’/>
     <Property name=’selectedTitle’ value=’_FM_SELECTED_RESOURCES’/>
     <Property name=’allowedValues’>
       <invoke name=’getUnassignedResources’ class=’com.waveset.ui.FormUtil’>
           <ref>:display.session</ref>
           <map>
             <s>current</s>
             <ref>waveset.resources</ref>
           </map>
       </invoke>
    </Property>
   </Display>
</Field>

Using listResourceObject Method

There are ten versions of the listResourceObject method. Some versions require that you supply a single resource ID, or a list of resources, or a Boolean to clear the cache or other caching details. Other versions provide the ability to specify that the method to run as a different user.

When implementing this method within a form or rule, clarify in comments which version of this method you are using. For example,

Lists the Groups on the AD-Austin resource starting at the OurGroups OU.
It will leverage the server cache should this list be found there.
Additional details in the Identity Manager formUtil javadocs under:
public static java.util.List listResourceObjects(java.lang.String subjectString,
java.lang.String objectType,
java.lang.String resourceId,
java.util.Map options,
java.lang.String cacheList)

Tricky Scenarios Using FormUtil Methods

Because most FormUtil processing involves views, the most common view-related method used in forms are the checkoutView and checkinView methods.

A typical checkout operation would be:


<Action id=’-1’ application=’com.waveset.session.WorkflowServices’>
   <Argument name=’op’ value=’checkoutView’/>
   <Argument name=’type’ value=’User’/>
   <Argument name=’id’ value=’mfairfield’/>
   <Variable name=’view’/>
   <Return from=’view’ to=’user’/>
</Action>

Using map of options with Checkout and Checkin Calls

Determining which options you can use as optional arguments for these check out and check in calls can be challenging. These optional arguments are defined as part of the UserViewConstants class. The Javadocs list options in this format:

OP_TARGETS

OP_RAW

OP_SKIP_ROLE_ATTRS

Instead of hard-coding these literal strings in your code when checking for options, we define constants that can be used throughout the code base to represent a string. While this is a good coding practice, you cannot reference a static field, such as OP_TARGET_RESOURCES, through XPRESS or workflow.

To identify valid strings that you can pass in the correct value, you can write a test rule that reveals the true string. For example, the following rule returns TargetResources.


<block>
   <set name=’wf_srv’>
      <new class=’com.waveset.provision.WorkflowServices’/>
   </set>

   <script>
      var wfSvc = env.get( ’wf_srv’ );
      var constant = wfSvc.OP_TARGETS;
      constant;
   </script>
</block>

Although handy for finding out a string, this rule does not lend itself to production deployment because it returns the same string for every call made to it.

One you’ve identified valid strings, you can update your checkout view call as follows. The following code checks out a view that only propagate changes to Identity Manager and AD.


<Action id=’-1’ application=’com.waveset.session.WorkflowServices’>
   <Argument name=’op’ value=’checkoutView’/>
   <Argument name=’type’ value=’User’/>
   <Argument name=’id’ value=’mfairfield’/>
   <Argument name=’options’>
      <map>
       <s>TargetResources</s>
       <list>
          <s>Lighthouse</s>
          <s>AD</s>
       </list>
     </map>
   </Argument>
<Variable name=’view’/>
<Return from=’view’ to=’user’/>
</Action>

Best Practices

From a performance perspective, best practice suggests limiting the size of the user view, whenever possible. A smaller view means less data is pulled from the resource and sent over the network. For instance, if a customer decides to implement a custom workflow for users to request access to a particular resource, that workflow should check out the user’s view to allow a change to be submitted to it (pending the appropriate approval, of course). In this example, it is likely that the only information that must be available is the Identity Manager User portion of the view so that the waveset.resources list and the accountInfo object can be updated appropriately. In that situation, use the TargetResources option when checking out the User view to only checkout the Identity Manager user portion of the User view with an option map similar to the following:


<map>
   <s>TargetResources</s>
   <list>
      <s>Lighthouse</s>
   </list>
</map>

Additional Options

The following options are used by a subset of the FormUtil methods:

scopingOrg

Use this option when two or more AdminRoles are assigned to a user. The value of this option should be the name of an organization. This value specifies that the returned names should consist only of names that are available to organizations that are controlled by an AdminRole. The AdminRole must control the scopingOrg organization and is assigned to the logged-in user.

This option is typically used to ensure that when a user is creating or editing another user, the member organization of the user being edited determines which names (for example, Resourcenames) are available for assignment.

Using the scopingOrg Parameter

Set this attribute under these conditions:

For example, under these circumstances:

the resources available for assigning to that user should be limited to the resources available to the organization(s) controlled by the Engineering AdminRole.

Implementing the scopingOrg Attribute

To implement the behavior described above, add the scopingOrg attribute to the waveset.resources field in the User form.

Reference the value of the current organization as follows:


<Field name=’waveset.resources’>
   <Display class=’MultiSelect’>
      <Property name=’title’ value=’_FM_PRIVATE_RESOURCES’/>
      <Property name=’availableTitle’
          value=’_FM_AVAILABLE_RESOURCES’/>
      <Property name=’selectedTitle’ value=’_FM_SELECTED_RESOURCES’/>
      <Property name=’allowedValues’>
         <invoke class=’com.waveset.ui.FormUtil’
           name=’getUnassignedResources’>
             <ref>:display.session</ref>
               <map>
                  <s>currentRoles</s>
                  <ref>waveset.roles</ref>
                  <s>currentResourceGroups</s>
                  <ref>waveset.applications</ref>
                  <s>current</s>
                  <ref>waveset.original.resources</ref>
                  <s>scopingOrg</s>
                  <ref>waveset.organization</ref>
               </map>
         </invoke>
      </Property>
   </Display>
</Field>

current

Specifies a list of names to be merged with those returned. For example, this is typically the list of selected names in a MultiSelect field to ensure that all selected names are in the MultiSelect’s list of available names.

conditions

This value contains a set of AttributeConditions that specify particular attributes, their expected values, and a comparison operator. AttribueConditions can be specified in three ways:

Table 2–23 Values of conditions Attribute

Value Format  

Description  

Map 

As a map containing <MapEntry> elements, each <MapEntry> element contains the attribute name to be matched as the key and the value to be matched as the value. (The operator is assumed to be “equals”.) If more than one attrname/value pair is specified, they will be logically and’ed together.

Example 

<Map>
<MapEntry key=’memberObjectGroups’ value=’Top’/>
</Map>

map 

As a map with no <MapEntry> elements, the first entry is the name of a queryable attribute supported by this type of object. The second entry is the value an object of this type must have for the associated queryable attribute to be returned. (The operator is assumed to be “equals”.)

If more than one attrname/value pairs is specified, they will be logically and’ed together. 

Example 

<map><s>memberObjectGroups</s>

<ref>waveset.organizations</ref>

</map>

list 

As a list of AttributeCondition objects. If more than one AttributeCondition is specified, they will be logically and’ed together. You must use this form if you must specify an operator other than ”equals’.

Example 

<list>

<newclass= ’com.waveset.object.AttributeCondition’>

<s>MemberObjectGroups</s>

<s>equals</s>

<ref>waveset.organization</ref>

</new>

</list>

Using the conditions Attribute

You can specify a list of one or more object type-specific query attribute conditions to filter the list of names returned by certain FormUtil methods. (These methods include methods that take an options map as an argument.) You can specify these query attribute conditions as a query option whose key is conditions and whose value can be specified as either a map or list of AttributeConditions.

Examples: Using the condition Attribute to Filter Names

The following examples illustrate the use of the conditions attribute to apply additional filters to the list of names returned by a FormUtil method that takes an options map as an argument. This example uses conditions to specify that only resources that support container object groups of type LDAP should be returned.


Example 2–12 First Example of Using the conditions Attribute


<Field name=’waveset.resources’>
   <Display class=’MultiSelect’ action=’true’>
...
      <Property name=’allowedValues’>
         <invoke class=’com.waveset.ui.FormUtil’ name=’getUnassignedResources’>
            <ref>:display.session</ref>
            <map>
               <s>currentRoles</s>
               <ref>waveset.roles</ref>
               <s>currentResourceGroups</s>
               <ref>waveset.applications</ref>
               <s>current</s>
               <ref>waveset.original.resources</ref>
               <s>conditions</s>
               <map>
                  <s>supportsContainerObjectTypes</s>
                  <s>true</s>
                  <s>type</s>
                  <s>LDAP</s>
               </map>
            </map>
         </invoke>
      </Property>
   </Display>
</Field>

This second example requests resources that support container objects where the resource has a name that starts with ldap. Note that the value for the queryable attributes are compared case-sensitive.


Example 2–13 Second Example of Using the conditions Attribute


<Field name=’orgResource’>
   <Display class=’Select’ action=’true’>
...
      <Property name=’allowedValues’>
         <invoke class=’com.waveset.ui.FormUtil’ 
                  name=’getResourcesSupportingContainerObjectTypes’>
            <ref>:display.session</ref>
            <map>
               <s>conditions</s>
               <list>
                  <new class=’com.waveset.object.AttributeCondition’>
                     <s>name</s>
                     <s>starts with</s>
                     <s>ldap</s>
                  </new>
               </list>
            </map>
         </invoke>
      </Property>
   </Display>
</Field>

Third Example of Using the conditions Attribute


<Field name=’accounts[Lighthouse].capabilities’>
   <Display class=’MultiSelect’>
         ...
     <Property name=’allowedValues’>
        <invoke class=’com.waveset.ui.FormUtil’
           name=’getUnassignedCapabilities’>
           <ref>:display.session</ref>
           <ref>waveset.original.capabilities</ref>
             <map>
             <s>conditions</s>
               <list>
                  <new class=’com.waveset.object.AttributeCondition’>
                    <s>name</s>
                    <s>starts with</s>
                    <s>bulk</s>
                  </new>
               </list>
             </map>
        </invoke>
     </Property>
   </Display>
</Field>

Supported Queryable Attribute Names

The list of supported queryable attribute names per object type are categorized as follows:

Other queryable attribute names are defined in the Identity Manager Schema Configuration configuration object (for example, firstname and lastname).

Supported Operators

Identity Manager performs all comparisons of queryable attributes with case-sensitive semantics. Furthermore, Identity Manager carries out comparisons using String comparison semantics., so 1000<999 (because String comparisons compare character by character, and 9 is greater than 1.