test

Sun Identity Manager Deployment Reference

Using the FormUtil Methods

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

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

FormUtil Class Methods

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

Understanding Method Context

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

Fetching Context

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

Invoking Methods

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

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

where the name field identifies the name of the method.

Calling FormUtil Methods without Knowing the Context

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

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

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

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


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

Best Practice

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


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

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

Commonly Invoked Methods

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

Method  

Description  

callResourceMethod 

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

buildDn, buildDns 

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

checkStringQualityPolicy 

Checks the value of a designated string against string policy. 

controlsAtLeastOneOrganization 

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

getObject 

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

getObjectNames 

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

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

getOrganizationsDisplayNames 

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

getResources 

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

getResourceObjects 

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

getRoles 

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

getUnassignedApplications 

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

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

getSubordinates 

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

getUnassignedResources 

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

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

getUsers 

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

listResourceIObjects 

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

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

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

This method has multiple variants that differ on whether: 

The method returns a single resource versus a resource list. 

The cache should be cleared. 

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

testObject 

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

testUser 

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

hasCapability, hasCapabilities 

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

Tips on FormUtil Usage

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

This section introduces basic hints for using these methods.

Using getObject to Fetch Objects from the Repository

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

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


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

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

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

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

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

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

Note –

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

Using getResourceObject to Fetch Objects from a Resource

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

Using the getUnassigned* Methods

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


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

Using listResourceObject Method

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

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

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

Tricky Scenarios Using FormUtil Methods

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

A typical checkout operation would be:


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

Using map of options with Checkout and Checkin Calls

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

OP_TARGETS

OP_RAW

OP_SKIP_ROLE_ATTRS

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

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


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

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

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

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


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

Best Practices

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


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

Additional Options

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

scopingOrg

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

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

Using the scopingOrg Parameter

Set this attribute under these conditions:

For example, under these circumstances:

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

Implementing the scopingOrg Attribute

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

Reference the value of the current organization as follows:


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

current

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

conditions

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

Table 2–23 Values of conditions Attribute

Value Format  

Description  

Map 

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

Example 

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

map 

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

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

Example 

<map><s>memberObjectGroups</s>

<ref>waveset.organizations</ref>

</map>

list 

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

Example 

<list>

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

<s>MemberObjectGroups</s>

<s>equals</s>

<ref>waveset.organization</ref>

</new>

</list>

Using the conditions Attribute

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

Examples: Using the condition Attribute to Filter Names

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

Example 2–12 First Example of Using the conditions Attribute


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

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

Example 2–13 Second Example of Using the conditions Attribute


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

Third Example of Using the conditions Attribute


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

Supported Queryable Attribute Names

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

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

Supported Operators

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