Sun Java System Identity Manager 6.0 Workflows, Forms, and Views 2005Q4M3 |
4
FormUtil Methods
This chapter describes the most commonly used FormUtil 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. Additional methods are provided to format string values such as dates and directory DNs.
Related Information
For examples on using these methods within forms, see the sections titled Using Hidden Components and Populating Lists in Forms.
Invoking MethodsUse 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.
Most FormUtil methods require that a LighthouseContext or Session object be passed as the first argument. That is available within forms 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 to remove the base context prefix.
MethodsThis section introduces the most commonly used FormUtil methods.
callResourceMethod Method
callResourceMethod(LighthouseContext s, String resourceName, String methodName, Map args) throws WavesetException {
Description
Invokes the specified method on the resource by passing it the specified arguments.
Parameters
buildDn Method
buildDn(String name,
String baseContext)
Description
Takes a name 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.
Parameters
Return Value
Returns a single value in the form CN=<name>,<baseContext>
Example
<invoke name='buildDn' class='com.waveset.ui.FormUtil'>
<s>North America</s>
<s>ou=marketing,dc=acme,dc=com</s>
</invoke>
This example returns: <s>CN=North America,ou=marketing,dc=acme,dc=com</s>
In XPRESS, this same function can be represented by:
<concat>
<s>CN=</s>
<s>North America</s>
<s>,</s>
<s>ou=marketing,dc=acme,dc=com</s>
</concat>
buildDns Method
buildDns(List names,
String baseContext)
or
buildDns(String names,
String delimiter,
String baseContext)
Description
Takes a list of names and the base context to append to each token in the list. Both variants of this method return a list of fully qualified DN names.
For example, passing in group1, group2 and dc=example, dc=com returns the list: cn=group1, dc=example, dc=com and cn=group2, dc=example, dc=com
Parameters
The first variant of this method takes the arguments described in the following table:.
The second variant of this method takes the three arguments described in the following table.
Return Values
Returns a list of values or strings, where each value is of the form CN=<name>,<baseContext>
Examples
Example 1: List buildDns
<invoke name='buildDns' class='com.waveset.ui.FormUtil'>
<list>
<s>North America</s>
<s>Europe</s>
</list>
<s>ou=marketing,dc=acme,dc=com</s>
</invoke>
This example returns:
<list>
<s>CN=North America,ou=marketing,dc=acme,dc=com</s>
<s>CN=Europe,ou=marketing,dc=acme,dc=com</s>
</list>
In XPRESS, this same function can be represented by:
<dolist name='commonName'>
<list>
<s>North America</s>
<s>Europe</s>
</list>
<concat>
<s>CN=</s>
<ref>commonName</ref>
<s>,</s>
<s>ou=marketing,dc=acme,dc=com</s>
</concat>
</dolist>
Example 2: List buildDns(String names, String delimeter, String baseContext)
<invoke name='buildDns' class='com.waveset.ui.FormUtil'>
<s>North America,Europe,China</s>
<s>,</s>
<s>ou=marketing,dc=acme,dc=com</s>
</invoke>
This example returns:
<list>
<s>CN=North America,ou=marketing,dc=acme,dc=com</s>
<s>CN=Europe,ou=marketing,dc=acme,dc=com</s>
<s>CN=China,ou=marketing,dc=acme,dc=com</s>
</list>
We do not recommend using XPRESS to provide this functionality.
checkStringQualityPolicy Method
checkStringQualityPolicy(LighthouseContext s, String policy, Object value, Map
map, List pwdhistory, String owner)
Description
Checks the value of a designated string against string policy.
Parameters
Return Values
true – Indicates that the string passed the policy tests.
false – Indicates that the string value does not meet the specified policy.
controlsAtLeastOneOrganization Method
controlsAtLeastOneOrganization(LighthouseContext s, List organizations)
throws WavesetException {
Description
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.
Parameters
Return Values
true – Indicates that the current authenticated Identity Manager user controls any one of the organizations in the list.
false – Indicates that the current authenticated Identity Manager user does not control any organizations in the list.
getObject Method
getObject(LighthouseContext s,
String typeName,
String id)
Description
Retrieves an object from the repository (subject to authorization).
Parameters
getObjectNames Method
getObjectNames(LighthouseContext s,
String typeName)
or
getObjectNames(LighthouseContext s,
String typeName,
Map options)
Description
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.
Parameters
Option
Value
conditions
See Additional Options.
current
See Additional Options.
scopingOrg
See Additional Options.
Return Values
This method returns a list of the names of objects of a given type to which the session owner has access.
getOrganizationsDisplayNames Method
getOrganizationsDisplayNames(LighthouseContext s)
throws WavesetException
or
getOrganizationsDisplayNames(LighthouseContext s, Map options)
throws WavesetException
Description
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.
Note This method defaults to the system configuration setting for useOrganizationDisplayNames only if the call to getOrganizationsDisplayNames() does not specify a pathPrefix option.
Parameters
Options consist of a map of key-value pair arguments.
Version-Specific Behavior
This method behaves differently depending upon whether you have installed the v3.1x version or later releases of Identity Manager. The 3.1.x version of this method does not support multiple organizations with the same name. Version 4.x and greater of this product do support multiple organizations with the same name.
Why use the v3.1.x Version of this Method?
Reset this method to not support multiple organizations if your customized installation is characterized by the following features:
- Duplicate organization names are not and will not be used, and the preference is to display organizations using the short display names
- Customizations use methods that previously returned the short name of the organizations
- You use the getOrganizations method to present the list of available organizations, or it used in evaluation expressions
- References to the waveset.organization view attribute (that previously returned the short name of the org) is used in expressions to set additional resource attributes to view attributes
Resetting this Method to v3.1.x Behavior
If you are running a version of Identity Manager that is higher than v3.1.x but want the behavior described above, you can edit the following system configuration object attribute as follows:
<Attribute name='useOrganizationDisplay Names'>
<Boolean>false</Boolean>
</Attribute>
getResources Methods
getResources(LighthouseContext s)
throws WavesetException
or
getResources(LighthouseContext s,
List current)
throws WavesetException
or
getResources(LighthouseContext s,
String matchType,
String value)
throws WavesetException
or
getResources(LighthouseContext s,
String matchType,
String value
List current)
or
getResources(LighthouseContext s,
Map Options)
Description
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.
- The first variant of this method takes session only and returns all resources that are visible to the administrator.
- The second variant of this method returns all resources and merges in the current list.
- The third variant of this method returns all resources that match a particular attribute value.
- The fourth variant of this method returns all resources that match a particular attribute value and merges in the current list.
Parameters
For a list of supported resource type names, see Views.
Option
Value
conditions
See Additional Options.
current
See Additional Options.
scopingOrg
See Additional Options.
Valid queryable attribute types for the matchType parameter include the following:
getResourceObjects Methods
getResourceObjects(LighthouseContext session, String objectType, String resourceId, Map options, String cacheList, String cacheTimeout, String cacheIfExists))
or
getResourceObjects(LighthouseContext session, String objectType, String resourceId, Map options)
or
getResourceObjects(String subjectString, String objectType, String resourceId, Map options)
or
getResourceObjects(String subjectString, String objectType, String resourceId, Map options, String cacheList, String cacheTimeout, String clearCacheIfExists)
Description
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.
Parameters
The second flavor of this method uses a subjectString instead of Session.
getRoles Method
getRoles(LighthouseContext s)
or
getRoles(LighthouseContext s, String current)
or
getRoles(LighthouseContext s, List current)
or
getRoles(LighthouseContext s, Map options)
Description
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.
Parameters
Parameter
Description
s
Identifies a valid Identity Manager session, typically referred to in forms as <ref>:display.session</ref>.
options
current, conditions, and scopingOrg. See table.
Option
Value
current
See Additional Options.
conditions
See Additional Options.
scopingOrg
See Additional Options.
Return Values
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 Method
getUnassignedApplications(LighthouseContext s, Map options)
throws WavesetException {
Description
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.
Parameters
getUnassignedApplications takes the following options:
Parameter
Description
context
Identity Manager context object
options
current, currentRoles, conditions. See table below.
getUnassignedResources Method
static public List getUnassignedResources(LighthouseContext s, Map
options) throws WavesetException
Description
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.
Parameter
Description
context
Identity Manager context object
options
availableToOrgScope, current, currentRoles, currentResourceGroups, conditions, scopingOrg. See table below.
Return Values
This method returns a list of resource names suitable for the private resources of a user.
getUsers Method
getUsers(LighthouseContext s)
or
getusers(LighthouseContext s, Map options)
Description
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.
Parameters
Parameters
Description
s
Identifies a valid Identity Manager context, typically referred to in forms as <ref>:display.session</ref>.
options
current, conditions, exclude, scopingOrg. See table below.
listResourceObjects Methods
listResourceObjects(LighthouseContext s,
String objectType,
List resourceList,
Map options,
String cacheList)
or
listResourceObjects(LighthouseContext s,
String objectType,
List resourceList,
Map options,
String cacheList,
String clearCacheIfExists)
The two preceding variants are the same except that the second method clears the cache.
listResourceObjects(String subjectString,
String resourceObjectType,
List resourceList,
Map options,
String cacheList)
or
listResourceObjects(String subjectString,
String objectType,
String resourceId,
Map options,
String cacheList)
String clearCacheIfExists)
or
listResourceObjects(String subjectString,
String objectType,
String resourceID,
Map options,
String cacheList)
or
listResourceObjects(String subjectString,
String objectType,
String resourceID,
Map options,
String cacheList)
String cacheTimeout
String clearCacheIfExists)
The two preceding variants are the same except that the second method clears the cache.
listResourceObjects(LighthouseContext session,
String objectType,
String resourceId,
Map options,
String cacheList,
String clearCacheIfExists)
throws WavesetException {
or
listResourceObjects(LighthouseContext session,
String objectType,
String resourceId,
Map options,
String cacheList)
throws WavesetException {
or
listResourceObjects(LighthouseContext session,
String objectType,
String resourceId,
Map options,
String cacheList)
String cacheTimeout
String clearCacheIfExists
throws WavesetException
or
listResourceObjects (String subjectString, String objectType, List resourceList, Map options, String cacheList, String clearCacheIfExists)
Description
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:
Parameters
Return Values
This method returns a list of resource object names of the specified resource object type from the list of resources (resourceList of IDs or names).
testObject Method
testObject(LighthouseContext s,
String typeName,
String id)
Description
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.
Parameters
Return Values
This method returns:
true – object exists
null – object does not exist
testUser Method
testUser(LighthouseContext s,
String id)
Description
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.
Parameters
Return Values
This method returns:
true – user exists
null – user does not exist
hasCapability Method
hasCapability(LighthouseContext s, String capability)
throws WavesetException {
Description
Checks to see if the user has a specified capability (String). This method checks for a capability that is assigned either directly or indirectly through AdminGroups and/or AdminRoles. Requires a session value.
Parameters
Parameter
Description
s
Identifies a valid Identity Manager context, typically referred to in forms as <ref>:display.session</ref>.
capabilities
Identifies the capability that will be queried for.
Return Values
hasCapability returns:
true – Indicates that the currently authenticated Identity Manager user has the specified capability.
false – Indicates that the current user does not have the specified capability.
hasCapabilities Method
hasCapabilities(LighthouseContext s, List capabilities)
throws WavesetException {
Description
Checks to see if the user has a list of specified capabilities (Strings). These capabilities can be assigned either directly or indirectly through AdminGroups and/or AdminRoles. Requires a session value.
Parameters
Return Values
hasCapabilities returns:
true – Indicates that the currently authenticated Identity Manager user has all the specified capabilities.
false – Indicates that the user does not have all the specified capabilities.
Additional Options
The following options are used by a subset of the FormUtil methods:
scopingOrg
Used when two or more AdminRoles are assigned to a user. The value should be the name of an organization. This value specifies that the returned names should contain only ones that are available to organizations that are controlled by an AdminRole that controls 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, if an administrator were assigned both the Engineering AdminRole and Marketing AdminRole, and the administrator is editing a user who is a member of the Engineering organization, the Resources available for assigning to that user should be limited to those 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 can be specified in three ways:
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.
Example 1
<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>
Example 2
<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>
Example 3
<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 UIConfig.xml (for example, firstname and lastname).
All Object Types
Account
AdminGroup
Queryable Attribute
Description
hidden
Identifies whether an AdminGroup is hidden from display
memberAdminGroups
Lists the AdminGroups that are directly assigned to this AdminGroup
AdminRole
Configuration
Queryable Attribute
Description
configType
Specifies the JAVA class name of the class that extends configuration (for example, UserUIConfig, UserForm)
Event
Queryable Attribute
Description
eventType
Specifies the type of event to enable grouping events that are similar
LoginApp
LoginModGroup
ObjectGroup
Queryable Attribute
Description
directoryJunction
Identifies whether the ObjectGroup is a directory junction
(true|false)
displayName
Specifies the readable name of the object group’s user
Policy
Resource
Role
Queryable Attribute
Description
role_resources
Lists the resources assigned to a role
role_approvers
Lists the approvers assigned to a role
WorkItem
User
Supported Operators