Chapter 2 Workflow Services

This 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 Built-in Variables

The 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.

Table 2-1 Workflow Built-In Variables
Name	Description
WF_ACTION_ERROR	A built-in variable that will be set to true if the previously executed action returned a result containing an error or a thrown exception.
WF_ACTION_RESULT	A built-in variable that will be set to the WavesetResult object returned by the previous action. Use this variable when you want to capture the action's WavesetResult and process it without adding it to the global TaskInstance result. It was originally added to support resource retries, where you do not necessarily want to keep adding the resource error messages to the task result on every retry. It is not used often, but can be useful if you ever want to tweak the action result before adding it to the task result.
WF_ACTION_SUPPRESSED	This built-in variable will be set to true if the action was suppressed due to a <Condition> expression evaluating to false.
WF_ACTION_TIMEOUT	A built-in variable that will be set to true if the previously executed action timed out.
WF_CASE_OWNER	A built-in variable that contains the name of the administrator that launched the workflow task.
WF_CASE_RESULT	A built-in variable that contains the WavesetResult of the TaskInstance. This can be used in Actions implemented in XPRESS or JavaScript to get a hold of the result. For Actions implemented as WorkflowApplication classes, they can obtain the result through the WorkflowContext. Since the entire WorkflowContext is exposed through the WF_CONTEXT variable, this is not absolutely necessary, but convenient.
WF_CONTEXT	A built-in variable that contains a WorkflowContext object. This can be used in Actions implemented in XPRESS or JavaScript to get a hold of the WorkflowContext. For Actions implemented as WorkflowApplication classes, the context is passed in.

General Session Workflow Services Call Structure

Workflow services are called from workflow actions. The general form of a session workflow service action is shown in the following code example:

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.

If an op argument is given that is not on the above list, the workflow services return:

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

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


Name	Required	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

Return Values and Side Effects

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.

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

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

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

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

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

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	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.

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

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

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

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

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:

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.

If an op argument is given that is not on the preceding list, the workflow services return:

approveProvision Provision Workflow Service

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

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

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:

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

authenticateUserCredentials Provision Workflow Service

Table 2-32 authenticateUserCredentials Method Arguments
Name	Required	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

Table 2-33 changeResourceAccountPassword Method Arguments
Name	Required	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

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

checkDeProvision Provision Workflow Service

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

createResourceObject Provision Workflow Service

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

deleteResourceAccount Provision Workflow Service

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

deleteResourceObject Provision Workflow Service

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

deProvision Provision Workflow Service

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

deleteUser Provision Workflow Service

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

disable Provision Workflow Service

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

enable Provision Workflow Service

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

getApprovals Provision Workflow Service

Determines the lists of approvals for the assigned role, organization, and resources for an existing account.

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.

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

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

provision Provision Workflow Service

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

questionLock Provision Workflow Service

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

reject Provision Workflow Service

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

reProvision Provision Workflow Service

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

runResourceAction Provision Workflow Service

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.

Return Values and Side Effects

updateResourceObject Provision Workflow Service

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.

Previous Contents Index Next
Sun Java[TM] System Identity Manager 7.0 Workflows, Forms, and Views

Name	Required	Valid Values	Description
op	yes	getApprovers
user	yes	GenericObject	Identifies the view that represents the user.


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.