Sun Java[TM] System Identity Manager 7.0 Workflows, Forms, and Views |
Chapter 2
Workflow ServicesThis chapter describes each of the Identity Manager workflow services that are available to the Identity Manager implementer who is modifying or creating custom workflows.
Identity Manager contains default workflows to define the process for provisioning and manipulating user accounts. During a customer implementation, you can modify these workflows to reflect the customer’s business rules. Workflow allows a customer’s business rules for account provisioning to be implemented in Identity Manager.
Related Chapters
- Workflow — Introduces Identity Manager workflows.
- Identity Manager Views — Identity Manager forms interact with an internal Identity Manager data structure called the user view. When customizing a form, you can call view attributes.
Workflow Built-in VariablesThe workflow engine uses several built-in variables. Most of these variables do not need to be declared in the workflow. Built-in variables can be used to find out the state of the workflow execution. In addition, many variables are set as a side effect of workflow services.
General Session Workflow Services Call StructureWorkflow services are called from workflow actions. The general form of a session workflow service action is shown in the following code example:
Code Example 2-1
Each of the supported workflow services has a variable number of required and optional arguments.
Supported Session Workflow Services
Identity Manager currently supports the following session workflow services. The op argument to the session workflow services call must be one of these values.
- addDeferredTask
- audit
- authenticateUserCredentials
- authorize
- checkinObject
- checkinView
- checkoutObject
- checkoutView
- checkStringQualityPolicy
- createView
- disableUser
- enableUser
- findUser
- getObject
- getProperty
- getResource
- getView
- getViewForm
- listResourceObjects
- queryObjectNames
- queryObjects
- queryReferencingRoles
- refreshView
- removeDeferredTask
- removeProperty
- setProperty
- unlockObject
- unlockView
If an op argument is given that is not on the above list, the workflow services return:
'Unknown WorkflowServices op'
and the workflow context variable WF_ACTION_ERROR will be non-null.
addDeferredTask Session Workflow Service
Used to set up the properties that are recognized by the Deferred Task Scanner task. Deferred Task Scanner typically iterates over WSUser objects looking for a property.
When using this method to set a deferred task on a user, you can set arbitrary values using the taskDefinition argument. This argument must be an object that contains the arbitrary values. These values will be passed into the workflow that is run when the deferred task is triggered.
Adding Multiple Versions of the Same Task Definition
This method supports the ability to add multiple versions of the same task definition to a user.
Passing additional arguments in the value of the taskDefinition attribute works only if taskDefinition is defined as a GenericObject. You cannot define taskDefinition as either a map or List.
Note
The built-in arguments, such as date and description, are already made available to the called workflow.
Table 2-2 AddDeferredTask Method Arguments
Name
Required
Valid Values
Description
type
no
list of types
Indicates the type of object that the deferred task will be added to. If not supplied, the type is defaulted to user.
name
yes
Specifies the name of the object to which the deferred task will be added.
task
no
Identifies the name of the TaskDefinition to run. If the taskDefinition argument is a string, then this argument is the name of the GenericObject that will be placed on the property list.
taskDefinition
no
Specifies the task definition. Can be either a string or Generic Object.
String -- If this argument takes the form of a string, then it defines either the Task Definition or Task Template name, and the task argument is the name of the GenericObject that will be placed on the property list.
Generic Object -- If this argument takes the form of a Generic Object, the taskDefinition argument is a preconstructed property listObject.
instanceName
no
Identifies the name of the TaskInstance to create.
date
no
Can be either a java.util.Date object or a string in the usual format
Specifies the date on which you want the deferred task to run.
organization
no
Indicates the organization in which to put the TaskInstance.
owner
no
Specifies the name of the effective owner of the TaskInstance (used for later management).
description
no
Specifies optional descriptive text to include with the TaskInstance for the task management page.
executeOnce
no
When set to true, indicates that the deferred task will be successfully executed only once.
If an error occurs during task execution, the task will continue to be executable by the deferred task scanner until the task completes successfully one time or is removed manually through a call to the removeDeferredTask method.
audit Session Workflow Service
Requests Identity Manager to record an audit event using Identity Manager’s audit services. The audit will be logged under the workflow administrator that launched the workflow (WF_CASE_OWNER).
Table 2-3 audit Method Arguments
Name
Required
Valid Values
Description
op
yes
audit
type
yes
see Type Names
The Identity Manager type of the object that is being audited.
logResultErrors
no
true/false
If false, this method logs the single error indicated by the other parameters. If true, it creates a log record for each error message in the task results. The task result is obtained from the workflow context. This is a convenient way to log all the errors accumulated during workflow execution.
name
no
Identifies the name of the object that is being audited.
status
no
success
failure
Indicates the audit status. If no status is supplied, the status is assumed to be failure.
reason
no
Currently hard-coded to DATABASE_ACCESS_FAILED (any value you use will be ignored).
action
yes
see Action Names
Indicates the Identity Manager action to audit.
resource
no
Specifies the resource that is being audited.
accountId
no
Identifies the accountId that is being audited.
error
no
Indicates the error that is being audited.
parameters
no
This is expected to be a java.util.Map object that contains name/value pairs. These pairs are specific to each event. For example, the parameter named RoleName is typically set for log records that are related to users.
attributes
no
This is expected to be a java.util.Map object that contains name/value pairs. This is formatted in the log record by the audit system in the following format: name1=value1;; name2=value2;;
It is typically used to log changes to specific account attributes.
organizations
no
Specifies a list of the organizations (also known as ObjectGroups) associated with the object being audited.
Return Values and Side Effects
An audit log is entered with the supplied information.
authorize Session Workflow Service
Requests that Identity Manager checks if the subject of the workflow is authorized with the given right for the given action on the given object. The subject of the workflow is the administrator that the workflow is running under. This will be the value of the WF_CASE_OWNER built-in variable.
Table 2-4 authorize Method Arguments
Name
Required
Valid Values
Description
op
yes
authorize
type
yes
see Type Names
Specifies the type of the object that is being authorized.
name
yes
Indicates the name of the object that is being authorized.
right
yes
see Right Names
Indicates the right to authorize.
action
yes
see Action Names
Specifies the action to authorize.
Return Values and Side Effects
If the WF_CASE_OWNER is not authorized to for the given right or action on the given object, WF_ACTION_ERROR will be true. The WavesetResult will contain the error.
checkStringQualityPolicy Session Workflow Service
Checks string quality against a specified policy.
Table 2-5 checkStringQualityPolicy Method Arguments
Name
Required
Valid Values
Description
policy
yes
Identifies the policy (String)
map
no
Provides a map of the data that the string must not contain (Map).
returnNull -- (Optional) If set to true, the method return a null object upon success.
value
yes
Specifies the value of the string to be checked. (Object)
pwdhistory
no
Lists user's previous passwords in uppercase, encrypted format.
owner
yes
Identifies the user whose string value is being checked.
Return Values and Side Effects
The method returns a checkPolicyResult object. A value of true indicates that the string passes the policy test. If the string does not pass the policy test, the method returns an error message. If you have set the returnNull option to true on the map parameter, the method returns a null object upon success.
checkinObject Session Workflow Service
Persists the current memory representation of the given object. Identity Manager makes sure that the administrator that launched the workflow is authorized to check in the object.
Note
Using views is more convenient than using objects. Try using views to modify objects. For information on Views, see the chapter titled Identity Manager Views.
Table 2-6 checkinObject Method Arguments
Name
Required
Valid Values
Description
op
yes
checkinObject
object
no
Indicates the object that is being checked in. If no object is supplied, the workflow service has no effect.
lockedBy
no
Specifies the alternate lock name that was used when locking the object.
Return Values and Side Effects
The object specified is checked in. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
checkinView Session Workflow Service
Checks in a view.
Table 2-7 checkinView Method Arguments
Name
Required
Valid Values
Description
op
yes
checkinView
view
no
Identifies the view to be checked in. If no view is specified, the checkinView workflow service has no effect.
Return Values and Side Effects
The specified view is checked in to the Identity Manager repository. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
checkoutObject Session Workflow Service
Obtains and locks a persistent Identity Manager object. Identity Manager makes sure that the administrator that launched the workflow is authorized to check out the object.
Note
Using views is more convenient than using objects. Try using views to modify objects. For information on views, see Identity Manager Views.
Table 2-8 checkOutObject Method Arguments
Name
Required
Valid Values
Description
op
yes
checkoutObject
type
yes
Indicates the type of the object that is being checked out.
name
yes
Specifies the name of the object that is being checked out.
lockedBy
No
Gives an alternate name to use to record the lock.
lockWait
No
Indicates the number of seconds to wait if there is contention on a lock.
Return Values and Side Effects
If the checkout is successful, the object checked out will be placed in the variable object. If the lock timed out, WF_ACTION_TIMEOUT will be set to true for the checkout action. If any other error occurred (including administrator not authorized to check out the object), WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
checkoutView Session Workflow Service
Fetches and locks an Identity Manager view.
Table 2-9 checkoutView Method Arguments
Name
Required
Valid Values
Description
op
yes
checkoutView
viewid
no
Identifies the ID of the view to checkout. If this argument is not specified, both the type and ID must be specified. Type and ID may be easier to use from workflows.
name
yes
Specifies the name of the object that is being checked out.
type
no
Identifies the type for the view.
id
No
The ID of the object being manipulated in the view. For example, if you are creating a view to manipulate an account object, this would be the accountId.
raiseViewErrors
no
Specifies that display.errors is promoted to WF_ACTION_ERROR. When set to true, errors in the display.errors attribute of the view are automatically extracted and returned to the workflow engine as errors. The WF_ACTION_ERROR workflow variable is set.
subject
no
The Identity Manager administrator to check out the view under. If this is not supplied, the administrator that launched the workflow will be used (WF_CASE_OWNER)
options
no
View-specific options. The values you can pass are specific to the view being used. The most common is the user view. Options can be found in session.UserViewConstants. The simpler views should declare their option constants in the *Viewer.java file. Probably the second most common view used from workflow is ProcessViewer, followed by PasswordViewer, DisableViewer, EnableViewer, and RenameViewer. These have comparatively few options.
Return Values and Side Effects
If the checkout is successful, the view checked out will be placed in the variable: view. If the lock timed out, WF_ACTION_TIMEOUT will be set to true for the checkout action. If any other error occurred (including administrator not authorized to check out the view), WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
createView Session Workflow Service
Creates an empty object of the type given with the appropriate form.
Table 2-10 createView Method Arguments
Name
Required
Valid Values
Description
op
yes
createView
viewid
no
Indicates the ID of the view to be created. If this argument is not specified, both the type and ID must be specified. Type and ID can be easier to use from workflows.
type
no
Specifies the type for the view
id
no
Identifies the ID of the object being manipulated in the view. For example, if you are creating a view to manipulate an account object, this would be the accountId.
options
no
Specifies view-specific options. The values you can pass are specific to the view being used. The most common is the user view. Options can be found in session.UserViewConstants. The simpler views should declare their option constants in the Viewer.java file. Probably the second most common view used from workflow is ProcessViewer, followed by PasswordViewer, DisableViewer, EnableViewer, and RenameViewer. These have comparatively few options.
Return Values and Side Effects
If the create is successful, the view will be placed in the variable view. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
disableUser Session Workflow Service
Disables one or more of a user’s resource accounts.
There are three ways to disable an account:
- Set com.waveset.provision.WorkflowServices op=disable. See the disableUser Session Workflow Service in this chapter. This is the lowest level disable method. It is implemented directly by the provisioning engine. No workflow, authorization, or auditing is involved.
- Set com.waveset.session.WorkflowServices op=disableUser.
- Set com.waveset.session.WorkflowServices op=checkoutView with arguments:
type=DisableViewer
id=<user account id>The second and third option are essentially the same. The second option checks out and checks in the Disable view. This is the equivalent of disabling a user from the Identity Manager interface. It launches the Disable User workflow as a side effect.
Use the provision.WorkflowServices method if you are implementing a customized Disable User process. Use one of the other approaches if you are implementing some other process and want to use the standard Disable User process to accomplish the disable.
Note
By default, Identity Manager disables the accounts. To not disable an account, add the following argument to the disableUser workflow:
<Argument name=’doWaveset’ value=’false’/>
Table 2-11 disableUser Method Arguments
Name
Required
Valid Values
Description
op
yes
disableUser
Specifies the ID of the view to be created. If this argument is not specified, both the type and ID must be specified. Type and ID can be easier to use from workflows.
doWaveset
no
true/false
Identifies a list of resources to disable. To not disable an account, set the value of this argument to false:
<Argument name=’doWaveset’ value=’false’/>
services
no
Specifies the ID of the view to be created. If this argument is not specified both the type and ID must be specified. Type and ID can be easier to use from workflows.
Return Values and Side Effects
The specified resource accounts are disabled. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
enableUser Session Workflow Service
Enables one or more of a user’s resource accounts.
Table 2-12 enableUser Method Arguments
Name
Required
Valid Values
Description
op
yes
enableUser
accountId
yes
Identifies the Identity Manager user to enable accounts for.
doWaveset
no
true/false
If true, the Identity Manager account is enabled for this user. If not supplied, it defaults to true, and the account is enabled.
services
no
Identifies a list of resources to enable. If this argument is not supplied, all of the user’s resource accounts will be enabled.
Return Values and Side Effects
The specified resource accounts are enabled. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
findUser Session Workflow Service
Finds a user in the Identity Manager repository. This functionality is older than the more flexible query method workflow services. Consider using the query method workflow services.
Table 2-13 findUser Method Arguments
Name
Required
Valid Values
Description
op
yes
findUser
attribute Name
yes
Identifies the name of the Identity Manager queryable attribute to search for the user on.
attribute Value
yes
true/false
Specifies the value of the queryable attribute to search for the user on.
Return Values and Side Effects
The accountId of the first user found that contains the given value for the given attribute will be placed in the accountId variable. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
getObject Session Workflow Service
Returns the Identity Manager object of the given name and type. The administrator that launched the workflow (WF_CASE_OWNER) will be check to see if it is authorized to get the object.
Note
Using views is more convenient than using objects. Try using views to view objects. See Identity Manager Views for more information.
Table 2-14 getObject Method Arguments
Name
Required
Valid Values
Description
op
yes
getObject
type
yes
see Type Names
Identifies the type of the object that is being fetched from Identity Manager.
name
yes
Specifies the name of the object that is being fetched from Identity Manager.
Return Values and Side Effects
The Identity Manager object with the given type and name will be placed in the object variable. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
getProperty Session Workflow Service
Obtains a property value from an Identity Manager object. Identity Manager makes sure that the administrator that launched the workflow is authorized to view the object.
Table 2-15 getProperty Method Arguments
Name
Required
Valid Values
Description
name
yes
getObject
Identifies the name of the object whose property is to be retrieved.
propertyName
no
see Type Names
Identifies the name of the property to obtain from the object. If no propertyName is given, the service has no effect or return
Return Values and Side Effects
If the propertyName is found on the object, the property's value will be placed in the variable propertyValue. If any error occurs (including administrator not being authorized to view the object), WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
getResourceObject Session Workflow Service
Retrieves a resource object specified by type and ID from the specified resource.
Table 2-16 getResourceObject Method Arguments
Name
Required
Valid Values
Description
resourceId
yes
Specifies a valid resource object.
objectType
no
see Type Names
Specifies a valid object type defined in the resource's <ObjectType> section.
objectId
Identifies a valid fully qualified object identifier on this resource (for example, dn).
options
Controls the behavior of the request.
Valid keys include searchAttrsToGet, which specifies a list (List) of objectType-specific attribute names to get.
Return Values and Side Effects
Returns the object (specified by objectType and objectId) from the specified resource.
getView Session Workflow Service
Fetches an Identity Manager view. The administrator that launched the workflow (WF_CASE_OWNER) will be check to see if it is authorized to get the view.
Table 2-17 getView Method Arguments
Name
Required
Valid Values
Description
op
yes
getView
viewId
no
Identifies the ID of the view to fetch. If this argument is not specified, both the type and ID must be specified. Type and ID may be easier to use from workflows.
type
no
Indicates the type for the view.
id
no
Specifies the ID of the object being fetched in the view. For example, if you are fetching a view to view an account object, this would be the accountId.
raiseViewErrors
no
true or false
Specifies that display.errors is promoted to WF_ACTION_ERROR. When set to true, errors in the display.errors attribute of the view are automatically extracted and returned to the workflow engine as errors. The WF_ACTION_ERROR workflow variable is set.
options
no
getView
Gives view-specific options. The values you can pass are specific to the view being used. The most common is the user view. These options can be found in session.UserViewConstants. The simpler views should declare their option constants in the *Viewer.java file. Probably the second most common view used from workflow is ProcessViewer, followed by PasswordViewer, DisableViewer, EnableViewer, and RenameViewer. These have comparatively few options.
Return Values and Side Effects
If the fetch is successful, the view will be placed in the variable view. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
getViewForm Session Workflow Service
Returns the form associated with the given view.
Table 2-18 getViewForm Method Arguments
Name
Required
Valid Values
Description
form
no
Identifies the argument that has been replaced by formId.
formId
no
Identifies the name or ID of the form to get.
op
yes
getViewForm
view
no
Indicates the view to fetch the form from. If this argument is not supplied, the getViewForm workflow service has no effect.
Return Values and Side Effects
If the fetch is successful, the form is placed in the variable form. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
listResourceObjects Session Workflow Service
Returns a list of resource object names of the specified resource object type from the specified list of resourceIds.
Table 2-19 listResourceObjects Method Arguments
Name
Require
Valid Values
Description
objectType
yes
Identifies the name of a valid object class for this specified resourceId. If null, the method returns objects of all object types as defined by:
the specified resId found within the specified search container
the scope and the specified search filter
resourceId
no
Identifies a single resourceId. This value is derived from the named resource. If this is null, the method looks for resourceIdsList argument.
resourceIdList
yes
Lists resourceIds. These IDs are derived from the named resources. This is only used if the resourceId argument is null (undefined).
options
no
Indicates a map of options that control the behavior of the search.
Options are described in the following table
Table 2-20 Option Values for listResourceObjects Method
Option
Description
searchContext
Specifies the context within which to perform the search. If not specified, the method attempts to get a value from RA_BASE_CONTEXT. If no value is available in RA_BASE_CONTEXT, the method searches from the logical top.
searchFilter
(Optional) in LDAP search filter format as specified in RFC 1558, of one or more object <attr name> <condition> <value> tuples either and'ed or or'ed together. If not specified, a filter will be constructed using the specified objectType.
searchScope
Specifies whether the search should be done on the current object, only within the context of the specified searchContext, or in all subcontext within the specified searchContext.
Valid values include object, oneLevel, or subTree. subTree indicates that the search should be performed on all sub contexts within the specified searchContext.
searchTimeLimit
Indicates the time limit in milliseconds that a search should not exceed.
searchAttrsToGet
Specifies the list of objectType-specific attribute names to get per object.
runAsUser
Specifies the user name this request is to be run as. If not specified, defaults to resource proxy admin user.
runAsPassword
Indicates the password of runAsUser. Required to authenticate with resource to run the list request as the specified user.
cache
Specifies whether the server caches the returned list of objects. A value of true causes the server to cache the returned list of objects. The default is false.
cacheTimeout
Set the number of milliseconds before the cache times out (valid only if cacheList is true). When the cache times out, the object will automatically be retrieved from the resource the next time objects are requested.
clearCache
Force the caches to be cleared and the objects to be refetched from the resource the next time they are requested.
queryObjectNames Session Workflow Service
Returns a list of names that match the query attributes specified.
Table 2-21 queryObjectNames Method Arguments
Name
Required
Valid Values
Description
op
yes
queryObjectNames
type
yes
Identifies the object type for which the search is performed.
attributes
no
Indicates a list or map of queryable attribute name/value pairs to use to query objects. If not supplied, all objects of the given type are returned.
single
no
true
false
If true, the query will return the name of the first object that matches the query specified, if false or not supplied, the query will return the names of all objects that match the query specified.
Return Values and Side Effects
If single is false or unspecified, the list of object names that satisfies the query attributes specified is placed into the variable queryResult. If single is true, the name of the first object that satisfies the query attributes specified is placed into the variable queryResult, If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
queryObjects Session Workflow Service
Returns a list of objects that match the query attributes specified.
This method accepts either:
Table 2-22 queryObjects Method Arguments
Name
Required
Valid Values
Description
op
yes
queryObjects
type
yes
Indicates the object type for which the search is performed.
attributes
no
Specifies either:
Map containing elements of type WSAttribute
List containing elements of type AttributeCondition
If not supplied, all objects of the given type are returned.
single
no
true
false
If true, the query will return the first object that matches the query specified. If false or not supplied, the query will return all objects that match the query specified.
Return Values and Side Effects
If single is false or unspecified, the list of objects that satisfies the query attributes specified is placed into the variable queryResult. If single is true, the first object that satisfies the query attributes specified is placed into the variable queryResult, If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
queryReferencingRoles Session Workflow Service
Returns a list of all roles that directly or indirectly reference the specified role. It requires the role argument, which specifies the role for which you want to identify associated roles.
Return Values and Side Effects
For a given role passed as role, this method returns the result in variable queryResult, which lists all of the Role objects in the Identity Manager repository that directly or indirectly reference the specified role.
refreshView Session Workflow Service
Refreshes an Identity Manager view.
Table 2-23 refreshView Method Arguments
Name
Required
Valid Values
Description
op
yes
unlockObject
view
no
Identifies the view that is to be refreshed. If this argument is not specified, the refreshView workflow service has no effect.
raiseViewErrors
no
true or false
Specifies that display.errors is promoted to WF_ACTION_ERROR. When set to true, errors in the display.errors attribute of the view are automatically extracted and returned to the workflow engine as errors. The WF_ACTION_ERROR workflow variable is set.
Return Values and Side Effects
If the refresh is successful, the refreshed view is placed in the variable view. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
removeDeferredTask Session Workflow Service
Used to remove a deferred task from an Identity Manager object. Identity Manager will ensure that the administrator that launched the workflow is authorized to view the object.
Table 2-24 removeDeferredTask Method Arguments
Name
Required
Valid Values
Description
type
no
valid values are the list of types
Identifies the type of the object that the deferred task will be added to. If not supplied, the type is defaulted to user.
name
yes
Specifies the name of the object that the deferred task will be added to.
task
no
Specifies the name of the TaskDefinition to run.
taskDefinition
no
Indicates the complete task definition object. This argument can be used in lieu of specifying all of the other task arguments below. If both a complete task object and any of the other arguments are provided, the singleton arguments override the value of that argument in the task definition object.
instanceName
no
Identifies the name of the TaskInstance to create.
date
no
Can be either a java.util.Date object or a string in the usual format
Specifies the date on which you want the deferred task to run.
organization
no
Indicates the organization to put the TaskInstance in.
owner
no
Indicates the name of the effective owner of the TaskInstance (used for later management).
description
no
Specifies optional descriptive text to include with the TaskInstance for the Task Management page.
removeProperty Session Workflow Service
Removes an Identity Manager object property. Identity Manager makes sure that the administrator that launched the workflow is authorized to view the object.
Table 2-25 removeProperty Method Arguments
Name
Required
Valid Values
Description
name
yes
Indicates the name of the object whose property is to be set.
propertyName
no
Specifies the name of the property to modify in the object. If no propertyName is given, the service has no effect or return.
Return Values and Side Effects
The Identity Manager object's property is removed. If any error occurs (including administrator not authorized to view the object), WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
setProperty Session Workflow Service
Sets the value of an Identity Manager object's property. Identity Manager makes sure that the administrator that launched the workflow is authorized to view the object.
Table 2-26 setProperty Method Arguments
Name
Required
Valid Values
Description
name
yes
setObject
Indicates the name of the object whose property is wanted
propertyName
no
see Type Names
Specifies the name of the property to obtain from the object. If no propertyName is given, the service has no effect or return
propertyValue
no
the value to set the property to
If no propertyValue is given, the property is set to null
Return Values and Side Effects
The Identity Manager object's property is set to the given value. If any error occurs (including administrator not authorized to view the object), WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
unlockObject Session Workflow Service
Unlocks an Identity Manager object. The administrator that launched the workflow (WF_CASE_OWNER) is checked to ensure that it is authorized to modify the object. Views are more convenient than using objects. Try using views to accomplish modifications to objects.
Table 2-27 unlockObject Method Arguments
Name
Required
Valid Values
Description
op
yes
unlockObject
type
yes
Identifies the type of the object that is being unlocked.
name
yes
Specifies the name of the object that is being unlocked.
lockedBy
no
Indicates the alternate lock name that was used when locking the object.
Return Values and Side Effects
If successful, the object specified is unlocked. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
unlockView Session Workflow Service
Unlocks an Identity Manager view.
Table 2-28 unlockView Method Arguments
Name
Required
Valid Values
Description
op
yes
unlockview
view
no
Indicates the view that is to be unlocked. If this argument is not specified, the unlockView workflow service will have no effect.
Return Values and Side Effects
If successful, the view specified is unlocked. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
Provision Workflow Services
There is also a set of services in com.waveset.provision.WorkflowServices, although they are used less often than the methods in com.waveset.session.WorkflowServices. These are the low-level primitives for performing account management. They are called by the stock workflows. In a custom workflow, you might want to use these or you might want to use the higher level views with checkoutView/checkinView, which will in turn launch the stock workflows.
General Provision Workflow Services Call Structure
Workflow services are called from workflow actions. The general form of a provision workflow service action is:
<Action class='com.waveset.provision.WorkflowServices'>
<Condition/>
<Argument name='op' value=workflowServiceOp/>
<Argument name=argname1>
<expression>value1expression</expression>
</Argument>
<Argument name=argname2>
<expression>value2expression</expression>
</Argument>
…
<Argument name=argnameN>
<expression>valueNexpression</expression>
</Argument>
</Action>
Each of the supported workflow services will have a variable number of required and optional arguments.
Supported Provision Workflow Services
Following is the list of provision workflow services that Identity Manager currently supports. The op argument to the workflow services call must be one of these values.
- approve
- auditNativeChangeToAccountAttributes
- bulkReprovision
- changeResourceAccountPassword
- checkDeProvision
- cleanupResult
- createResourceObject
- deleteResourceAccount
- deProvision
- disable
- enable
- getApprovals
- getApprovers
- lockOrUnlock
- notify
- provision
- questionLock
- reject
- reProvision
- runResourceAction
- unlinkResourceAccountsFromUser
- updateResourceObject
- validate
If an op argument is given that is not on the preceding list, the workflow services return:
‘Unknown WorkflowServices op’
and the workflow context variable WF_ACTION_ERROR will be non-null.
approveProvision Provision Workflow Service
Records the approval of a user account.
Table 2-29 approveProvision Method Argument
Name
Required
Valid Values
Description
op
yes
approve
user.waveset.accountId or accountId
yes
Indicates the name of the Identity Manager user to approve.
options
no
Indicates the options to specify provisioning characteristics. See the javadocs for com.waveset.provision.
ProvisioningOptions.
Return Values and Side Effects
A WavesetResult object containing the result of the approval.
auditNativeChangeToAccountAttributes Provision Workflow Service
Reports native changes to one or more auditable attributes of a resource account.
Table 2-30 auditNativeChangeToAccountAttributes Method Arguments
Name
Required
Valid Values
Description
op
yes
auditNativeChangeToAccountAttributes
user.waveset.accountId or accountId
yes
Indicates the name of the Identity Manager user to audit.
resource
yes
Specifies the resource where native changes took place that are being audited.
prevAttributes
no
Map
Identifies the map of name/value pairs of the attributes before the change.
newAttributes
no
Map
Identifies the map of name/value pairs of the attributes after the change.
formattedChanges
no
Map
Specifies the formatted changes to be logged.
Return Values and Side Effects
A WavesetResult object containing the result of the audit.
bulkReprovision Provision Workflow Service
The method executes a set of queries to find all users that match the given conditions. It then iterates over this list and reprovisions the users one at a time.
To use this method to support automatic reprovisioning on every role update, add the following field to the Role form:
<Field name='processInputs.reprovision'>
<Expansion><s>true</s></Expansion>
</Field>
Table 2-31 bulkReprovision Method Arguments
Parameter
Description
role
Specifies role name
roles
Lists role names
organization
Specifies name of organization
organizations
Lists organization names
conditions
Provides a map of query options suitable for LighthouseContext.list Objects
options
Specifies provisioning options (for example, targets and fetches)
maxErrors
Specifies the maximum number of errors to tolerate before halting processing
Return Values
successes - Identifies users that were successfully reprovisioned
failures - Identifies users that could not be fully reprovisioned
authenticateUserCredentials Provision Workflow Service
Authenticates the user against the resource using the password.
Table 2-32 authenticateUserCredentials Method Arguments
Name
Required
Valid Values
Description
resourceName
yes
Specifies the name of the resource to authenticate against.
accountId
yes
Specifies the ID of this account, as it appears on the named resource.
accountPassword
yes
Specifies the password for this account (an unencrypted string).
Return Values
Returns the result of the call to authenticate. Sets a variable in the WFContext, passwordIsValid, to true on success or anything else on failure.
changeResourceAccountPassword Provision Workflow Service
Changes the password for one or more resource accounts.
Table 2-33 changeResourceAccountPassword Method Arguments
Name
Required
Valid Values
Description
op
yes
resources
yes
Specifies the list of resources for which to change the password.
options
no
Specifies options to specify provisioning characteristics. See the javadocs for com.waveset.provision.ProvisioningOptions.
Return Values and Side Effects
A WavesetResult object containing the result of the password change.
cleanupResult Provision Workflow Service
Removes null ResultErrors from the task result. This method takes the op argument, with a valid value of cleanupResult.
Return Values and Side Effects
A WavesetResult object containing the result of the cleanup.
checkDeProvision Provision Workflow Service
Determines if an account needs deprovisioning before deletion.
Table 2-34 checkDeProvision Method Arguments
Name
Required
Valid Values
Description
op
yes
checkDeProvision
Identifies the name of the Identity Manager user to check for deprovisioning need.
user.waveset.accountId or accountId
yes
Indicates the name of the user to check for deprovisioning need.
Return Values and Side Effects
A WavesetResult object containing the result of the cleanup.
createResourceObject Provision Workflow Service
Creates a resource object (for example, a group).
Table 2-35 createResourceObject Method Arguments
Name
Required
Valid Values
Description
op
yes
createResourceObject
object
no
GenericObject
If not specified, the service looks for an argument named after the ObjectType. For example, if a resource supports managing a group ObjectType, and if the object argument is not supplied, then the service will expect the resource object to be in an argument called group. Preferred practice is to use the object argument.
objectType
yes
Identity Manager resources can specify object types that they manage. This is specified by the ObjectType element list defined in the resource’s prototype XML. This argument is the name of one of those ObjectType.
resourceId
yes
Specifies the object ID for the resource on which to create the object.
Return Values and Side Effects
A WavesetResult object containing the result of the object creation.
deleteResourceAccount Provision Workflow Service
Deletes a resource account.
Table 2-36 deleteResourceAccount Method Arguments
Name
Required
Valid Values
Description
op
yes
deleteResourceAccount
user.waveset.accountId or accountId
yes
Indicates the name of the Identity Manager user to delete.
resource
yes
Identifies the name of the resource whose account needs to be deleted.
Return Values and Side Effects
A WavesetResult object containing the result of the account deletion.
deleteResourceObject Provision Workflow Service
Deletes a resource object (for example, a group).
Table 2-37 deleteResourceObject Method Arguments
Name
Required
Valid Values
Description
op
yes
deleteResourceObject
objectType
yes
Identity Manager resources can specify object types that they manage. This is specified by the ObjectType element list defined in the resource’s prototype XML. This argument is the name of one of those ObjectTypes.
object
no
GenericObject
If not specified, the service looks for an argument named after the ObjectType. For example, if a resource supports managing a group ObjectType, and if the object argument is not supplied, then the service will expect the resource object to be in an argument called group. Preferred practice is to use the object argument.
resourceId
yes
Specifies the object ID for the resource on which to delete the object.
Return Values and Side Effects
A WavesetResult object containing the result of the object creation.
deProvision Provision Workflow Service
Deletes an Identity Manager account and/or resource accounts.
Table 2-38 deProvision Method Arguments
Name
Required
Valid Values
Description
op
yes
deProvision
accountId
yes
Identifies the name of the Identity Manager user to deprovision.
subject
no
Specifies the effective subject for the call. If not supplied, the task’s subject is used. If the value of this argument is none, then no authorization is performed.
options
no
If not supplied, specific arguments below are used. If supplied, any specific arguments below override the same argument contained in this options map.
Return Values and Side Effects
A WavesetResult object containing the result of the deprovision.
deleteUser Provision Workflow Service
Deletes an Identity Manager user.
Table 2-39 deleteUser Method Arguments
Name
Required
Valid Values
Description
op
yes
deleteUser
subject
no
Identifies the effective subject for the call. If not supplied, the task’s subject is used. If the value of this argument is none, then no authorization is performed.
user.waveset.accountId or accountID
yes
Specifies the name of the Identity Manager user to approve.
options
no
Map
A value map of option name/option value pairs. If not supplied, the specific arguments given below are used. If supplied, any specific arguments below will override the same argument contained in this options map.
user.waveset.accountId or accountID
yes
Specifies the name of the Identity Manager user to delete.
adminName
no
Specifies the name of the administrator performing the deletion.
loginAppName
no
Identifies the login application name.
force
no
true/false
If true, the user will be deleted regardless of whether there are resource accounts that need to be deprovisioned or not.
Return Values and Side Effects
A WavesetResult object containing the result of the deletion of the user.
disable Provision Workflow Service
Disables an Identity Manager account and/or resource accounts.
Table 2-40 disable Method Arguments
Name
Required
Valid Values
Description
op
yes
disable
subject
no
The effective subject for the call. If not supplied, the task’s subject is used. If the value of this argument is none, then no authorization is performed.
options
no
A value map of option name/option value pairs. If not supplied, specific arguments below are used. If supplied, any specific arguments below will override the same argument contained in this options map.
accountId
no
adminName
no
Specifies the name of the administrator performing the operation.
loginAppName
no
Identifies the login application name.
doLighthouse
no
true/false
Indicates whether or not to disable the Identity Manager account.
doResources
no
true/false
Indicates whether or not to disable the user’s resources.
doAuthenticators
no
true/false
If true, disables all pass-through authentication resources.
Return Values and Side Effects
A WavesetResult object containing the result of the disable.
enable Provision Workflow Service
Enables an Identity Manager account and/or resource accounts.
Table 2-41 enable Method Arguments
Name
Required
Valid Values
Description
op
yes
enable
subject
no
Indicates the effective subject for the call. If not supplied, the task’s subject is used. If the value of this argument is none, then no authorization is performed.
options
no
Map
A value map of option name/option value pairs. If not supplied, specific arguments below are used. If supplied, any specific arguments below will override the same argument contained in this options map.
accountId
no
Identifies the name of the Identity Manager user to enable.
adminName
no
Indicates the name of the administrator performing the operation.
loginAppName
no
Specifies the login application name.
doLighthouse
no
true/false
Indicates whether or not to enable the Identity Manager account.
doResources
no
true/false
Indicates whether or not to enable the user’s resources.
doAuthenticators
no
true/false
If true, enables all pass-through authentication resources.
Return Values and Side Effects
A WavesetResult object containing the result of the enable.
getApprovals Provision Workflow Service
Determines the lists of approvals for the assigned role, organization, and resources for an existing account.
Table 2-42 getApprovals Method Arguments
Name
Required
Valid Values
Description
op
yes
getApprovers
user
yes
GenericObject
Identifies the view that represents the user.
Return Values and Side Effects
If the getApprovals workflow is successful, a GenericObject describing the approvals necessary for the user is returned in the approvals variable. If any error occurred, WF_ACTION_ERROR will be true, and the WavesetResult will contain the error.
lockOrUnlock Provision Workflow Service
Locks or unlocks a specified user if the Lighthouse Account Policy associated with the user specifies a lock expiration time.
The user is unlocked when one of these conditions is met:
While a user is locked, the user cannot log in by any login application interface (for example, the User or Administrator Interfaces). By default, the lock service is called by the Failure activity of the Password Login process that is invoked when the number of failed password login attempts exceeds those allowed by the user’s Lighthouse Account policy.
Argument
lock -- (Boolean) Indicates whether the user is locked (true indicates locked).
Return Values and Side Effects
This method returns null if it is a lock request. If it is an unlock request, this method returns a WavesetResult that contains the unlock results.
notify Provision Workflow Service
Sends a notification, which is almost always an email.
Table 2-43 notify Method Arguments
Name
Required
Valid Values
Description
op
yes
notify
type
yes
Indicates the type of notification. If not entered, email type will be used.
various other arguments
no, but should be supplied.
Identifies the arguments passed to the notifier. Map of name/value pairs.
Return Values and Side Effects
A WavesetResult object containing the result of the notify.
provision Provision Workflow Service
Creates a new Identity Manager account and (optionally) resource accounts.
Table 2-44 provision Method Arguments
Name
Required
Valid Values
Description
op
yes
Provision
user
yes
GenericObject
Specifies the GenericObject that contains the view that is to be provisioned
various provisioning options
no
Identifies the options to specify provisioning characteristics. See the javadocs for com.waveset.provision.ProvisioningOptions.
Return Values and Side Effects
A WavesetResult object containing the result of the provision.
questionLock Provision Workflow Service
Locks the user but does not set a lock expiration time or date.
A user who is locked with this service can be explicitly unlocked by an administrator who has the Unlock User capability. If an administrator does not unlock this user, his account is automatically unlocked the next time the user's password is changed or reset. While a user is locked by this service, he can still log in by any other Identity Manager application interface except the Forgot My Password page.
By default, the questionLock service is called by the Failure activity of the Question Login process, which is invoked when the number of failed question login attempts exceeds those allowed by the user's Lighthouse Account Policy.
Return Values and Side Effects
Returns null.
reject Provision Workflow Service
Records the rejection of a resource account.
Table 2-45 reject Method Arguments
Name
Required
Valid Values
Description
op
yes
reject
user.waveset.accountId or accountId
yes
Identifies the name of the Identity Manager user to reject.
options
no
Map
Indicates the options to specify provisioning characteristics. See the javadocs for com.waveset.provision.ProvisioningOptions
Return Values and Side Effects
A WavesetResult object containing the result of the rejection.
reProvision Provision Workflow Service
Updates an existing Identity Manager account.
Table 2-46 reProvision Method Arguments
Name
Required
Valid Values
Description
op
yes
reProvision
user
yes
GenericObject
Identifies the GenericObject that contains the view that is to be re-provisioned.
various provisioning options
no
Indicates the options to specify provisioning characteristics. See the javadocs for com.waveset.provision.ProvisioningOptions.
Return Values and Side Effects
A WavesetResult object containing the result of the reprovision.
runResourceAction Provision Workflow Service
Executes a resource action on the specified resource adapter for a resource.
You can specify the resource action either directly (using resourceAction) or by ID (using resourceId). If resourceAction correctly references a resource action, it overrides the ID specified in resourceId.
This method does not contain an authorization check. All the rules governing resource actions apply.
Table 2-47 runResourceAction Method Arguments
Name
Required
Valid Values
Description
resourceId
Identifies the resource to use.
resourceAction
(Optional) Specifies the resource action to run. This value overrides the ID specified in resourceId.
resourceActionId
Identifies by ID the resource action that the adapter runs.
resourceActionArgs
Provides a map of the arguments that this method should use. These arguments are passed to the script in the action as environment values, where the names of the variables are RESACTIONARG_<key> and the value is the value that corresponds to that key. Keys and values should be strings.
Note
The variables are accessed as described above with one exception: HostAccessResourceAdapter subclasses that support ACTIONS use JavaScript for running actions, and the arguments are passed in a global variable called additionalArgs.
Return Values and Side Effects
A WavesetResult object containing the results of the executed action
updateResourceObject Provision Workflow Service
Updates a resource object (for example, a group).
Table 2-48 updateResourceObject Method Arguments
Name
Required
Valid Values
Description
op
yes
updateResourceObject
objectType
yes
Identity Manager resources can specify object types that they manage. This is specified by the ObjectType element list defined in the resource’s prototype XML. This argument is the name of one of those ObjectTypes.
group
yes
GenericObject
Specifies the GenericObject to update on the resource. If not specified, the service looks for an argument named after the ObjectType. For example, if a resource supports managing a group ObjectType. If the object argument is not supplied, then the service expects the resource object to be in an argument called group. Preferred practice is to use the object argument.
resourceId
yes
Specifies the object ID for the resource on which to update the object.
Return Values and Side Effects
A WavesetResult object containing the result of the object update.
Type NamesThese are the valid type names that are used by Identity Manager:
- AdminGroup
- Administrator
- Application
- AttributeDefinition
- AuditConfig
- AuditLog
- AuditLogPrunerTask
- AuditQuery
- Configuration
- DataStore
- DataType
- Discovery
- Encryptionkey
- EmailTemplate
- Event
- Extract
- LoadConfig
- Log
- LoginConfig
- NotifyConfig
- ObjectGroup
- Policy
- RemedyConfig
- ReportCounter
- ReportLog
- Resource
- ResourceAccount
- ResourceObject
- Role
- RoleAttribute
- Rule
- TaskDefinition
- TaskInstance
- TaskResult
- TaskResultPage
- TaskSchedule
- TaskTemplate
- TestItem
- UsageReport
- User
- UserExternalAttribute
- WorkItem
Right NamesThese are the valid right names that are used by Identity Manager:
Action NamesThese are the valid action names that are used by Identity Manager: