Editing a Form

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

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

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

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 Waveset 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 Waveset forms. By default, the buttons are labeled Save and Cancel.

To 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

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

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:

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

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

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

Typical container components are described in the following table.

Creating a Simple Table

The <SimpleTable> component is a frequently used container component in Waveset 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.

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:

• Populating lists with the allowedValues property

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

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:

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

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

Adding a Multiselection List of Groups

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

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

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

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>

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

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

Creating a Text Entry Field in a Selection List

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

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

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

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.

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:

• Change User Password Form

• Deprovision Form

• Disable Form

• Enable Form

• Rename Form

• Reprovision Form

• Reset User Password Form

• Unlock Form

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

• accountDisplayName (string)

• accountId (string)

• directlyAssigned (true/false)

• disabled (yes/no)

• exists (yes/no)

• id (string)

• lastPasswordUpdate (string)

• resource (string)

• selected (true/false)

• type (string)

• userPwdRequired (yes/no)

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

• section header

• calendar icon

• back link

Adding a Section Heading to a Form

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

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

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

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

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

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

Using Hidden Components

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

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

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

• Adding a Password Confirmation Challenge

• Including XPRESS Logic Using Derivation and Expansion elements

• Calling Methods to Populate Lists

  • Building DN strings

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

  • Getting a list of organizations

  • Getting a list of unassigned resources

  • Obtaining a list of resource object names

  Disabling components

• Hiding components

Adding a Password Confirmation Challenge

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

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

• changePassword (by default, Change Password form)

• reset PasswordForm (by default, Reset User Password form)

You specify this property differently for each form.

Setting the RequiresChallenge Property for User Forms

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

<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, Waveset will challenge the current administrator who is requesting the change to enter the password he used to log in to Waveset. If the challenge is not successful (that is, the current administrator's password is not entered), Waveset will not permit the challenge. If the challenge is successful, Waveset 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.

Examples of <Derivation> Statements

The following two examples illustrate the potential use for the Derivation

• Example 1: Specifying an authoritative source for a global field

• Example 2: Mapping one set of values into another set

Example 1:

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

<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: Implementing a rule to standardize the case of text entered in a field

• Example 2: Hiding expansion logic

Example 1:

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

The use of the global attribute in fields sets any of the resources that have this value when the form is saved. When you load this form, Waveset 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:

• Obtain a list of resource object names

• Obtain a List of Resource Objects without Map Options

• Build DN strings

• Retrieve a list of accessible object types

• Retrieve a list of object types accessible by the session owner

• Get a list of organizations with prefixes

• Get a list of organizations without prefixes

• Get a list of organizations display names with prefixes

• Retrieve a list of applications unassigned to the user

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

Understanding Resource Object Names

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

The following table lists the object types supported by Waveset.

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.

Obtaining a List of Resource Objects without Map Options

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

In the following example:

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

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

• null value indicates no map options.

• value of true tells the server to cache the results.

        <invoke name=’listResourceObjects’
           class=’com.waveset.ui.FormUtil’>
              <ref>:display.session</ref>
              <s>UnassignedTokens</s>
              <s>SecurID</s>
              <null/>
              <s>false</s>
        </invoke>

Obtaining a List of Resource Objects with Map Options

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

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

Example:

In the following example

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

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

• A value of true tells the server to cache the results.

• A value of false tells the server not to cache the results.

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

• Account

• Administrator

• Configuration

• EmailTemplate

• Resource

• Role

• System

• TaskInstance

• User

• UserForm

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>

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>

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

Hiding Fields

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

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

<Field name=’field A’/>

Calculating Values

Methods for dynamically calculating values within forms include:

• Generating field values

• Including rules in forms

• Including XPRESS statements in a form

Generating Field Values

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

Including Rules in Forms

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

• a list of corporate departments

• default values

• a list of office buildings

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 Waveset to add data transformation capabilities to forms and to incorporate state transition logic within Waveset 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 Waveset tasks:

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

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

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

The expressions contained in these elements can be used throughout Waveset.

Example Expression

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

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

This function is passed two arguments:

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

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

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

Example of Expression Embedded within Form

The following example shows the use of XPRESS logic embedded within an Waveset 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

Waveset 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, Waveset displays this asterisk after the text field that follows the attribute name.

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

To Customize the Resource Schema Map

1. Using the Waveset 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

Waveset supplies two types of online help:

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

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

How to Specify Guidance Help for a Component

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

Matching the Component’s title Property with a Help Entry

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

Overriding Guidance Help

You can use a custom message catalog to override the guidance text that displays in a pop-up window. If you name your custom message catalog defaultCustomCatalog, Waveset 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 Waveset 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

• Inserting Javascript into a form

• Testing whether a user or object exists

• Inserting Alert Messages into XPRESS Forms

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

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

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

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

• Transition logic between pages is simple

• Privileged system calls between pages are required

Wizard forms contain the two rows of buttons described below.

This second row of button can vary as follows:

Implementing a Wizard Form

Wizard form syntax closely resembles tabbed user form structure. ,

To 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

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

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

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

  <Field name=’Page2’>
     <Display class=’EditForm’/>
     <Disable><neq><ref>showPage2</ref><s>true</s></neq></Disable>
  ...
  </Field>

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

Alternatives to the Default Create and Edit User Forms

When an administrator uses the default User form to edit a user, all resources that are owned by a user are fetched at the moment an administrator begins editing a user account. In environments where users have accounts on many resources, this potentially time-intensive operation can result in performance degradation. If you are deploying Waveset 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 Waveset’s Edit and Create User interfaces in environments with many users and resources. This improved performance results from several features, including:

• incremental resource fetching

• selective browsing of a user’s resources

• multiple resource editing

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

Incremental Resource Fetching

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

Selective Browsing

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

Multiple Resource Editing

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

When to Use Scalable Forms

Consider using scalable forms when

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

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

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

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

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

• Resource Table User form, which provides an alternative to the default Tabbed User form.

Dynamic Tabbed User Form

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

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.

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

Step 1: Import the Form

1. From the Waveset 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. Waveset responds with a message that indicates that the import was successful.

Step 2: Change Form Mapping

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

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

• Separately assign the Scalable User Form to a particular administrator(s). If this is your choice, see Step 2: Change Form Mapping.

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

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

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

Step 1: Import the Form

1. From the Waveset 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:

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

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

• operations that are updated when the final save operation occurs.

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

• ./ACF2UserForm.xml

• ./ActivCardUserForm.xml

• ./ADUserForm.xml

• ./AIXUserForm.xml

• ./BlackberryUserForm.xml

• ./ClearTrustUserForm.xml

• ./HP-UXUserForm.xml

• ./NDSUserForm.xml

• ./OS400UserForm.xml

• ./PeopleSoftCompIntfcUserForm.xml

• ./RACFUserForm.xml

• ./SAPPortalUserForm.xml

• ./SolarisUserForm.xml

• ./SunISUserForm.xml

• ./TopSecretUserForm.xml

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

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

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.

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, Waveset 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 Waveset password synchronization mechanism by following these three steps:

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

To 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