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 Identity Manager, such as a database.

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

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

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