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’/>