Sun[TM] Identity Manager 8.0 Workflows, Forms, and Views |
Chapter 1
WorkflowThis chapter describes Sun Identity Manager workflow.
Topics in this Chapter
Related Chapters
- XPRESS Language – Lists and describes use expressions written in the XPRESS language to include logic in workflows and forms.
Understanding WorkflowIdentity Manager workflow defines a sequence of actions and tasks that are performed consistently according to a defined rule set. Using the Identity Manager Integrated Development Environment (IDE) graphical interface, you can customize each workflow launched by Identity Manager.
Before working with workflow, develop an understanding of:
What is Workflow?
In general terms, a workflow is a logical, repeatable process during which documents, information, or tasks are passed from one participant to another for action, according to a set of procedural rules. A participant is a person, machine, or both.
In Identity Manager, this concept is specifically implemented as the Identity Manager workflow component, which comprises multiple processes (workflows) that control creation, update, enabling, disabling, and deletion of user accounts.
Depending upon where you are in the product interface, workflows are referred as workflows, tasks, process, or TaskDefinitions.
When is Workflow Used?
Most Identity Manager tasks you perform are defined as a set of workflow processes. When you create a user in Identity Manager, for example, the corresponding workflow process defines and conducts activities that:
Workflows can run automatically without any user interaction or require user interaction in the form of an approval.
Workflows are typically launched as a side effect of checking in a view. Views are checked in when you click Save on a page that implements forms and views.
Workflows in the Repository
Within the Identity Manager repository, a workflow exists as a configuration object, typically of Type WFProcess. (The single exception to this object definition is the Create User workflow, which is defined as a ProvisioningTask object.) The taskType is always Workflow.
Task Definitions and Task Definitions
The launched instance of a TaskDefinition is represented as a TaskInstance object. You can view both object types from the Debug page. To access either Task Definitions or Task Instances current for your deployment, follow these steps:
- From the Debug page of the Identity Manager Administrator Interface, select TaskDefinition from the Type menu adjacent to the List Objects button
- Click List Objects. Identity Manager displays a list of the available object types that you have access to.
- Select an object (for example, TaskDefinition). Identity Manager displays all instances of that object type that you have permission to see.
Once a workflow task is launched, the workflow engine creates a TaskInstance in the repository. A TaskInstance is an object in the repository that holds the runtime state of an executing workflow process. It stores context variables and immediate transition information for the TaskDefinition from which it was spawned.
The TaskInstance references the descriptive TaskDefinition object through the TaskDefinition object's generated ID. If you edit a TaskDefinition, TaskInstances already in execution will continue to use the old TaskDefinition object, but new ones will use the modified TaskDefinition with its newly generated ID.
When Are Task Instances Deleted?
The life of a TaskInstance is determined by the resultLimit parameter. If the result limit is zero, the task will be deleted immediately after completion. If it is positive, the value is the number of minutes that the TaskInstance is kept.
To delete a suspended workflow TaskInstance
Task Definition Parameters
The following table lists the standard configuration parameters.
Workflow Engine
The workflow engine is a software service that provides the run-time execution for a workflow process. The functions provided by the workflow engine to support a workflow process include:
Identity Manager captures activity-level variables for activities that contain a manual action. To minimize the storage needed for a workflow task, the workflow engine removes all other variables (before export) for completed activities to minimize the storage needed for a workflow task.
Workflow Process Components OverviewEach workflow process is defined by one or more of the following components. These components are discussed at greater length below.
- Activity – Represents a single, logical step in the process.
- Action – Defines how an activity is accomplished. An action can be a simple expression evaluation or a call to a complex Java class.
- Transition – Defines the movement from one activity to the next.
- Split – Defines the movement from a single activity to more than one activity. Splits are further defined as:
- Join – Defines the movement from multiple activities to a single activity. Join components are further defined as:
- Subprocess – Defines a set of activities, actions, and transitions that can be called from other activities in the process.
Figure 1-1 General Workflow Process and Components
Workflow Activity
An activity is a single step in the workflow process. An activity can contain multiple components, including transitions, variables, and actions, but must contain start and end activities.
Neither start nor stop activities have associated actions. A start activity has one or more transitions to the activity that begins the process, but end activities should have no actions associated with them.
Workflow Action
A workflow action describes an operation that is performed within a workflow Activity. Each activity can contain multiple actions. Identity Manager provides the following types of actions.
- Application -- A simple automatic invocation of an application, linked through the WorkflowApplication interface. Application actions can receive arguments and variables, and return variables. Identity Manager provides a comprehensive set of applications for provisioning actions, Repository access, and other utilities.
- Manual -- An action that requires human interaction. Identity Manager forms can specify the names of variables to be requested of the user, and create a WorkItem in the repository for the owner(s) of the action.
- Expression -- An automatic action that is defined using an XPRESS language expression. Script actions are typically XPRESS or JavaScript programs.
- Subprocess -- An action performed by recursively invoking another workflow process. Subprocesses can be defined within the root process only.
Workflow Action Variables
What is an Application Action?
Application actions permit you to invoke more complex Java calls than you can invoke with script actions.
What is a Manual Action?
A manual action is part of the workflow process definition that defines a manual interaction. When the Workflow Executor processes a manual action, Identity Manager creates a WorkItem object in the Repository. The work item must be marked complete before the workflow can proceed. You must associate an owner with a Manual Action. An owner can be an expression that determines an owner.
Because most manual actions are used to solicit approvals, the work item table is located under the Approvals tab of the Administrator Interface. Any manual action that belongs to a workflow is represented by a WorkItem object in the Repository.The WorkItem view contains a few attributes that pertain to the WorkItem object itself, as well as values of selected workflow variables copied from the workflow task. These include attributes, such as owners of pending approvals, and the form used to approve the WorkItem.Identity Manager incorporates ManualActions in the standard workflow and allows approvals for organizations, roles, and resources.
You can assign a time-out to a manual action.
Default Workflow ProcessesUsing the Identity Manager IDE, you can edit the default Identity Manager processes to follow a custom set of steps. The Identity Manager workflow capability includes a library of default workflow processes, which includes:
- User workflows — Define the steps for tasks related to Identity Manager users, including creating, deleting, updating, enabling, disabling, and renaming users.
- Identity Manager object workflows — Define the steps for all tasks related to Identity Manager objects, including resources, resource groups, organizations, and organizational units. For example, some workflows, such as the Manage Role and Manage Workflows workflows, simply commit view changes to the repository, while providing hooks for approvals and other customizations.
- Miscellaneous workflows — Define the steps for various Identity Manager features and objects such as reconciliation, Remedy templates, and other custom tasks.
Example
The following Create User workflow has been modified to call an escalate activity if a timeout value is reached. If the time out is not reached, then the results of the APPROVED variable are evaluated. The results of the evaluation determines whether to transition to the approved or rejected activity.
WorkItem Types
Manual actions have the ability to assign a type to the work item that is generated when the manual action is executed by the workflow engine. You can assign the work item type in a customization to filter the set of v to be displayed or operated upon.
The following work item types are recognized by the system.
Table 1-3 Work Item Types
Work Item Type
Description
approval
Indicates that the work item represents an approval.
wizard
Indicates that the work item represents an arbitrary interaction with the user.
suspend
Indicates that the work item is temporary. Use this type to force a workflow into background execution.
In addition, you can assign customized work item types. For example, you might set the work item type to resource to represent a resource approval and role to represent a role approval.
WorkItem Context
Work items are launched using the <ManualAction> directive. The form associated with a specified workflow can set the base context to variables.user. This eliminates the need to put user.variables in the variable name.
The WorkItem is the name space, so typical attribute names of the form:
Applies to both custom tasks and administrator approvals.
Authorization Types
Manual actions can also specify the authorization type of the WorkItem to be created. The authorization type differs from the item type in that the system automatically filters the work items returned in a query to exclude those for which the current administrator is not authorized. Typically, any administrator with the Approver capability is authorized to view all work items in the organizations they control.
To specify a work item authorization type in the manual action, use the authType attribute as follows:
<ManualAction authType='RoleApproval'>
Assigning WorkItem Types
To specify an item type in the ManualAction definition, set the itemType attribute as shown in this example:
<ManualAction itemType='approval'>
Restricting Administrative View Capabilities for WorkItems
Typically, any administrator with the Approver capability is authorized to view all work items in the organizations they control. If you want an administrator to view only a subset of the work items in an organization, follow these steps:
- Define new authorization types that extend the WorkItem type. For example, define the RoleApproval type.
- Define new capabilities that have rights on the new authorization types rather than WorkItem itself. For example, define a Role Approver capability that has rights on the RoleApproval type.
- Assign the Role Approver capability to an administrator rather than the general Approver capability
- Set appropriate authorization types in each manual action in your workflows.
Work Item Delegation
To enable delegation of work items (manual actions) in your workflow, you will need to pass delegator and delegators as input arguments and reference them in the <WorkItemDelegator> and <WorkItemDelegators> elements of the <ManualAction>, respectively.
You can obtain the value of delegator and delegators by invoking the com.waveset.provision.getDelegateObjects workflow service method, which takes the following arguments:
- One of the following two attributes:
- delegateWorkItemType - Specifies the work item type for which you want to get delegation information (that is, approval, roleApproval or attestation). Valid work item types are defined in the WorkItemTypes configuration object.
- delegateWorkItemTypeObjectName - Specifies the name of the object for which delegation information is to be gathered. Note that this argument is valid only if the delegateWorkItemType is either organizationApproval, resourceApproval, roleApproval or any extensions of those types.
- delegateWorkItemTypeObjectType - Specifies the type of object for which delegation information is to be gathered. Note that this argument is valid only if the delegateWorkItemType is either organizationApproval, resourceApproval, roleApproval or any extensions of those types.
The service returns a list of delegate objects in the delegateObjects argument.
delegateObject
Each delegateObject contains the following attributes:
- approver – Specifies the approver of this work item.
- delegator – Specifies the initial, or first delegator, for the work item. This user is set as the <WorkItemDelegator> for the work item.
- delegators – Lists delegator names ordered from first to last (before the final approver). This list of users is set as the <WorkItemDelegators> element for a manual action. If no delegation was found, this value is null.
Creating Transitions
Transitions define the rules by which an activity moves to one or more other activities. A transition can be conditional, which means that it will be taken only if certain conditions are met. Simple activities can contain only one unconditional transition that is taken as soon as the actions within the activity are complete.
Updating a Process for Identity Manager UseIf you customize a process, validate and save your changes to ensure that the workflow process completes correctly and as you expect. After saving, import the modified workflow for use in Identity Manager. You can also use the Identity Manager IDE debugger. For information on the Identity Manager IDE to edit workflow processes, see Using the Identity Manager IDE.
Editing a Workflow in Production
Do not customize a workflow process in a production environment.
Problems can emerge if you edit workflow activities or actions while instances of the original workflow are running. Specifically, the TaskInstance contains a reference to the workflow TaskDefinition and stores the current activity or action by ID. Changing these IDs may prevent the task from restarting where expected when execution resumes.
If you cannot avoid editing a workflow in a production environment, use the following procedure. It will help prevent the loss of pending work items from task instances that are using the old definition.
Following this procedure will help prevent problems with existing Create User tasks that may be in a suspended state within Identity Manager. This allows the TaskDefinition to keep its unique ID, which is referenced inside suspended tasks.
Standard WorkflowsIdentity Manager ships with standard workflows that are mapped to used processes. See Default Workflow Activities for a brief introduction to these default workflows. To display and edit a default workflow
- Open the Identity Manager IDE. For information on using the Identity Manager IDE, see Introduction to the Identity Manager IDE in Identity Manager Deployment Tools.
- Select File > Open Repository Object > Workflow Processes. The Identity Manager IDE displays the Workflow Processes list, which contains the standard workflow processes and any custom workflows in your deployment.
- Double-click on the name of the workflow you want to display or edit.
You can view process mappings by selecting Configure > Form and Process Mappings from the Identity Manager Administrator Interface.
General Categories of Default Workflows
Customizing a ProcessYou can change one or more of the Identity Manager processes to eliminate steps, include new steps, or customize existing steps. Each step in the process is represented by an activity.
The Workflow Toolbox facilitates workflow changes by providing pre-defined activities you can use when editing or creating a workflow.
To open the toolbox, right-click in the diagram view and select the toolbox option.
Default Workflow Activities
By category, these default activities are available.
Table 1-4 Default Workflow Activities
Activity
Description
Add Deferred Task
Adds deferred task scanner information to an object.
Audit Object
Creates audit log records.
Authenticate User Credentials
Authorize Object
Tests authorization for a subject on an object in the repository.
Checkin Object
Commits changes to an object.
Checkin View
Commits an updated view.
Checkout Object
Locks and retrieves a repository object for editing.
Adds deferred task scanner information to an object.
Checkout View
Gets an updateable view.
Create Resource Object
Creates a resource object.
Create View
Initializes a new view.
Delete Resource Object
Deletes a resource object.
Deprovision Primitive
Deprovisions resource accounts.
Disable Primitive
Disables resource accounts.
Disable User
Disables an Identity Manager user account, resource accounts, or both.
Email Notification
Sends email notification of an action.
Enable Primitive
Enables resource accounts.
Enable User
Enables an Identity Manager user account, resource accounts, or both.
Get Object
Retrieves a repository object.
Get Property
Retrieves a property.
Get View
Gets a read-only view.
List Resource Objects
Query Object Names
Searches for objects with matching attributes.
Query Objects
Searches for objects with matching attributes.
Query Reference
Refresh View
Refreshes a view that was previously checked out.
Remove Deferred Task
Removes deferred task scanner information from an object.
Remove Property
Removes an extended property on an object.
Reprovision Primitive
Reprovisions resource accounts.
Run Resource Actions
Set Property
Adds an extended property to an object.
Unlock Object
Unlocks an object that was previously checked out.
Unlock View
Unlocks a view that was previously checked out.
Update Resource Object
Modifies an object managed by a resource.
Table 1-5 Default Approval Workflows
Activity
Description
Approval
Performs the fundamental single approver process.
Approval Evaluator
Recursively evaluates an Approval Definition Object to implement a complex approval process.
Allows the form and template to be used to be passed in, but those can be overridden if specified in the set.
Lighthouse Approval
Performs the default Identity Manager approval process for assigned organizations, roles, and resources. Uses the Approval Evaluator process.
Multi Approval
Distributes approvals among multiple approvers. Users the Approval process for each approver.
Notification Evaluator
Recursively evaluates an Approval Definition Object to implement a complex notification process. The structure is expected to be the same as that defined for Approval Evaluator. In the standard workflow, approval definitions and notification definitions are maintained in the same structure. This is not required for a customized workflow.
Provisioning Notification
Standard process for notifying administrators after a provisioning operation has completed.
Table 1-6 Default User Workflows
Activity
Description
DeProvision
Performs the standard steps to deprovision an existing Identity Manager user, with granular control over resource account deletion, Identity Manager user deletion, unlinking, and de-assignment. Individual resource operations are re-tried until successful.
Provision
Performs the standard steps to create a new Identity Manager user and provision resource accounts. Individual resource operations are re-tried until successful.
Set Password
Changes the password of the Identity Manager account and resource accounts.
Update User Object
Checks out a WSUser object, applies a set of changes, and checks in the object.
Update User View
Checks out the user view, applies a set of supplied updates, and checks in the user view.
Update View
Applies a collection of changes to any view.
Table 1-7 Default End User Workflows
Activity
Description
End User Update Groups
Updates the group assignments on resources (that support groups) assigned to one of a manager's reports.
End User Update My Groups
Updates the group assignments on resources (that support groups) assigned to the logged-in account.
End User Update Roles
Updates the role assignments for one of a manager's reports.
End User Update My Roles
Updates the role assignments assigned to the logged-in account.
End User Update Resources
Updates the resource assignments and associated attributes for one of a manager's reports.
End User Update My Resources
Updates the resource assignments and associated attributes for the logged-in account.
Table 1-8 Default Compliance Workflows
Activity
Description
Access Review Remediation
Remediation for a single remediator working with a single UserEntitlement
Attestation
Creates a work item for each Attestor, and marks the User entitlement record as APPROVED when all work items complete with approved status, or REJECTED as soon as the first work item rejects. When one work item rejects, all other work items are canceled.
Launch Access Scan
Either launches or schedules an Access Scan Task, depending upon the setting provided by the Access Review task. It is directly called from the Access Review Workflow/Task.
Launch Entitlement Rescan
Launch a rescan of an Access Scan for a single user
Launch Violation Rescan
Launch a rescan of an Audit Policy Scan for a single user
Multi Remediation
Remediation for a single Compliance Violation and multiple remediators
Remediation
Remediation for a single Remediator working with a single Compliance Violation
Scan Notification
Notifies Attestors at the end of each Access Scan that they have pending Attestation workitems. Sends one notification to each Attestor, regardless of the number of pendng workitems. Also notifies the can owner (if any) that the scan has started and completed. This workflow takes the following input:
scanName -- name of access scan
scanOwner -- name of access scan owner
recipients -- list of Identity Manager user names which should be notified
notificationType --Valid types include begin, end, attest
userCount -- number of users to be scanned (only on begin)
Standard Attestation
Creates an Attestation Subprocess for each attestor specified.
Standard Attestation
Creates an Attestation Subprocess for each attestor specified.
Test Auto Attestation
Facilitates testing new Review Determination rules without creating Attestation work items. This workflow does not create any work items, and simply terminates shortly after it starts. It leaves all User Entitlement objects in the same state that they were created in by the access scan. Use the Terminate and Delete options to clean up the results from access scans run with this workflow.
Update Compliance Violation
Mitigates a Compliance Violation
Scan Task Variables
The Audit Policy Scan Task and Access Scan Task task definitions both specify the forms to be used when initiating the task. These forms include fields that allow for most, but not all, of the scan task variables to be controlled.
Table 1-9 Scan Task Variables
Variable Name
Default Value
Purpose
maxThreads
5
Identifies the number of concurrent users to work at one time for a single scanner. Increase this value to potentially increase throughput when scanning users with accounts on very slow resources.
userLock
5000
Indicates time (in mS) spent trying to obtain lock on user to be scanned. If several concurrent scans are scanning the same user, and the user has resources that are slow, increasing this value can result in fewer lock errors, but a slower overall scan.
scanDelay
0
Indicates time (in mS) to delay between issuing new scan threads. Can be set to a positive number to force Scanner to be less CPU-hungry.
Workflow Task
Table 1-10
Activity
Description
Add Result
Adds a named data item to the task result.
Add Result Error
Adds an error message to the task result.
Add Result Message
Adds an informational message to the task result.
Background Task
Forces the workflow into the background if it was launched from the Identity Manager Administrator interface.
Get Resource Result
Retrieves the result object returned by a resource adapter on the last provisioning operation.
Get Resource Result Item
Retrieves one result item from the result object returned by a resource adapter on the last provisioning operation.
Rename Task
Renames the task instance in the repository.
Scripted Task Executor
Executes BeanShell or JavaScript based on a provided script. As a task, it can be scheduled to run periodically. For example, you can use it to export data from the repository to a database for reporting and analysis. Benefits include the ability to write a custom task without writing custom Java code. (Custom Java code requires a re-compile on every upgrade and must be deployed to every server because the script is embedded in the task there is no need to recompile or deploy it.)
Set Result
Adds an entry to the task entrance result. This will appear in the workflow summary report.
Set Result Limit
Sets the number of seconds the task instance should be retained in the repository when it finishes. A non-negative value indicates that the task instance will be kept for this many seconds after the task has completed.
A negative value indicates that the task instance will never be removed automatically. However, you can remove it manually.
Using the Default Rename Task
To use the default rename task without customization, include the following action in your workflow:
<Action process='Rename Task'>
<Argument name='name' value='New Task Name'/>
</Action>
Tracking Workflow Progress
The designated owner of a task can always check on the status of a Workflow task. The owner is usually the person that initiated the task, but ownership can be redefined. Because tasks are objects in the repository, they will also be visible to anyone else with sufficient permissions.
Workflow status is typically represented in the Task List State column by the strings executing, pending, creating, and suspended. You can add additional, more informative strings summarizing workflow status to this column display.
Implement this feature by adding one of two possible expressions to the WFProcess file:
Code Example 1-2
<WFProcess name='queryRoleTask' maxSteps='0'>
<Status>
<s>Customized Status</s>
</Status>
<Activity id='0' name='start'>
<Transition to='GetReferencingRoles'/>
</Activity>
<Activity name='GetReferencingRoles'>
<Action id='0'>
<expression>
<Status> can be any XPRESS statement that results in a string. For example,
<Status>
<s>custom string</s>
</Status>
or
<Status>
<block>
<s>not appearing</s>
<s>custom string</s>
</block>
</Status>
The results of this expression, if any, are displayed in the Status column when a result is pending (for example, pending (custom status)).
Configuring Workflow PropertiesThe System Configuration object controls workflow configuration properties. The following table lists the most frequently configured properties.
Table 1-11 Workflow Properties in System Configuration Object
Attribute Name
Data Type
Default Value
workflow.consoleTrace
String
false
workflow.fileTrace
null
workflow.maxSteps
String
5000
workflow.resultTrace
String
false
workflow.retainHistory
String
false
workflow.traceAllObjects
String
false
workflow.traceLevel
String
1
workflow.validationLevel
String
CRITICAL
serverSetting.default.reconciler
consoleTrace
Specifies whether trace messages are emitted to the console. When set to true, trace messages are emitted. Default is false.
fileTrace
Specifies whether trace messages are emitted to a named file. To send trace messages to a specific file, enter the file name.
maxSteps
Specifies the maximum number of steps allowed in any workflow process or subprocess. Once this level is exceeded, Identity Manager terminates the workflow. This setting is used as a safeguard for detecting when a workflow is stuck in an infinite loop. The default value set in the workflow itself is 0, which indicates that Identity Manager should pull the actual setting value from the global setting stored in the SystemConfiguration object's workflow.maxSteps attribute. The value of this global setting is 5000.
resultTrace
Specifies whether trace messages should be retained in the task's result object. When set to true, trace messages accumulate in the task's result object.
retainHistory
Indicates whether the entire history should be returned after the task has completed. When set to true, Identity Manager returns the entire case history. Although it can useful to examine the history when diagnosing process problems, complete results can be large.
traceAllObjects
Indicates whether generic objects should be included in workflow trace operations.
traceLevel
Specifies the level of detail included in workflow trace. An unspecified or 0 value generates the most detail. The default is 1.
validationLevel
Identifies the level of strictness that is applied when validating workflows prior to running them. Errors of this level or greater will result in the workflow not being run. Valid values are CRITICAL, ERROR, WARNING, or NONE, where NONE turns off validation completely.
The default is CRITICAL.
serverSettings.default.reconciler Attributes
You can use these two reconciler attributes to tune per-account workflows:
- maxRetries - Specifies the maximum number of times that Identity Manager retries a failed reconciliation request. The default value is 3. Increasing this number will increase reconciliation time, but will also increase the chances of failed requests that eventually succeed.
- lockwaitThreshold - Specifies the minimum number of milliseconds that must past between reconcile request retry attempts. The default is 5000 milliseconds (5 seconds). Increasing this number will increase the time required to retry failed attempts, but increases time available to resolve outstanding issues.
The product of these two values should be at least the time required for the customer's per account workflows to succeed. This interval will allow for lock-contention issues to resolve internally in the reconciler.
Consider the following scenario:
The total time spent retrying will be 15 seconds (3 x 5000 milliseconds).
This configuration is not optimal because the total time spent retrying (15 seconds) is less than 30. The customer in this example scenario should increase the lockwaitThreshold and maxRetries values so that their product exceeds total per-account workflow time.
Using Workflow ServicesIdentity Manager contains default workflows to define the process for provisioning and manipulating user accounts. When customizing Identity Manager, you can modify these workflows to reflect the business rules that are unique to your deployment environment. Workflow allows you to implement unique business rules for account provisioning in Identity Manager.
This section provides a high level discussion of the following workflow service-related topics:
For information on specific workflow methods, see <distribution>\REF\javadoc, where <distribution> is your installation directory.
Understanding Method Context
The Lighthouse context represents an authenticated session to access the Identity Manager repository, which is subject to authorization checking to enforce visibility and action restrictions. Creating, modifying, and deleting users and other Identity Manager objects required authenticated access to the repository provisioner. This access is established by a context object, typically a LighthouseContext, or a WorkflowContext. Each of these context objects contains an authenticated session object that gives the caller access to the repository.
A context (or Session) is fairly intuitive when operating in the context of a 'logged in environment -- specifically, in a web browser. But within Identity Manager, a workflow is a separate process (actually a TaskInstance), and independent from any browser session, must still access the Identity Manager repository. This is possible because the executing workflow has an active context that is assigned to the workflow when it starts and can be persisted/restored with the workflow when it suspends/resumes.
When a user interacts with a workflow (typically through a WorkItem or ManualAction), the workflow maintains its own context. It does not assume the context of the user interacting with the WorkItem (although that user must possess a context that gives them appropriate access to the WorkItem). If the user interacting with the WorkItem causes a form to be loaded, Identity Manager process the form with the context of the user, not the context of the workflow. To be more precise, the user interacting with the WorkItem is not interacting with the workflow at all. The user is simply interacting with the WorkItem. After the user modifies the WorkItem, the Scheduler will restart the workflow if appropriate.
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. However, you can use built-in variables to find out the state of the workflow execution. In addition, many variables are set as a side effect of workflow services.
Note
Workflow variables are case-sensitive. For example, WF_ACTION_ERROR is not the same as wf_action_error.
Table 1-12 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. This variable 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 who 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 retrieve the result. For actions that are implemented as WorkflowApplication classes, they can obtain the result through the WorkflowContext. Because 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. You can use this in actions implemented in XPRESS or JavaScript to retrieve the WorkflowContext. For actions that are implemented as WorkflowApplication classes, the context is passed in.
General Session Workflow Services Call Structure
Workflows have an internal hierarchical structure that constrain both flow of control and scope of variables. A workflow (also called a Case or WFCase) contains a list of workflow Activity elements. A workflow activity contains a list of Action elements. A variable declared at the WFCase is visible to all Activity and Action elements. If a variable named color is declared at the WFCase level, and then again in an Action, they are effectively two different variables, such that changing the value of the color variable in the Action will not affect the value of the color variable from the WFCase.
Workflow services are called from workflow actions. WorkflowServices provides a set of operations that are selected through the value of the op Argument. Each operation can have a different set of arguments, so the calling 'signature' must match the specified service itself. The general form of a workflow service action is shown in the following code example:
<Action class='com.waveset.session.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 has a variable number of required and optional arguments. The op argument to the session workflow services call must specify one of the provided services. This is similar to calling a method by reflection, where the name of the method to be called is similar to the name of the workflow service to be executed.
If an op argument is given that is not on the following list, the workflow services return:
'Unknown WorkflowServices op'
and the workflow context variable WF_ACTION_ERROR will be non-null.
If an op argument is given that is not on the preceding list, a workflow service returns:
'Unknown WorkflowServices op'
and the workflow context variable WF_ACTION_ERROR will be non-null.
Provision Workflow Services
The com.waveset.provision.WorkflowServices class also contains a set of services, although they are used less often than the methods in com.waveset.session.WorkflowServices. These are the low-level primitives for performing account management, and they are primarily called by the default workflows. In a custom workflow, you might want to use these services, or you might prefer to use the higher level views with checkoutView and checkinView, which will in turn launch the stock workflows.
The primary purpose of the provison services is to give workflows access to the Provisoner, which in turn has access to Resources and resource accounts. These are the services that actually perform the read/write operations on the resources themselves.
General Provision Workflow Services Call Structure
Workflows have an internal hierarchical structure that constrain both flow of control and scope of variables. A Workflow (also called a Case or WFCase) contains a list of Workflow Activity. A Workflow Activity contains a list of Actions. A variable declared at the WFCase is visible to all Activity and Action elements. If a variable named 'color' is declared at the WFCase level, and then again in an Action, there are effectively two different variables, such that changing the value of the 'color' variable in the Action will not affect the value of the 'color' variable from the WFCase. Workflow services are called from workflow actions. WorkflowServices provides a set of 'operations' that are selected through the value of the 'op' Argument. Each operation may have a different set of arguments, so the calling 'signature' must match the service itself. The general form of a session workflow service action is shown in the following code example:
<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.
Table 1-13
Provision Workflow Service
Description
approve
Records the approval of a user account.
auditNativeChangeToAccountAttributes
Reports native changes to one or more auditable attributes of a resource account.
authenticateUserCredentials
Authenticates the user against the resource using the password.
bulkReprovision
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.
changeResourceAccountPassword
Changes the password for one or more resource accounts.
checkDeProvision
Determines if an account needs deprovisioning before deletion.
cleanupResult
Removes null ResultErrors from the task result. This method takes the op argument, with a valid value of cleanupResult.
createResourceObject
Creates a resource object (for example, a group).
deleteResourceAccount
Deletes a resource account.
deleteResourceObject
Deletes a resource object (for example, a group).
deProvision
Deletes an Identity Manager account and/or resource accounts.
deleteUser
Deletes an Identity Manager user.
disable
Disables an Identity Manager account and/or resource accounts.
enable
Enables an Identity Manager account and/or resource accounts.
getApprovals
Determines the lists of approvals for the assigned role, organization, and resources for an existing account.
getApprovers
lockOrUnlock
Locks or unlocks a specified user if the Lighthouse Account Policy associated with the user specifies a lock expiration time.
notify
Sends a notification, which is almost always an email.
provision
Creates a new Identity Manager account and (optionally) resource accounts.
questionLock
Locks the user but does not set a lock expiration time or date.
reject
Records the rejection of a resource account.
reProvision
Updates an existing Identity Manager account.
runResourceAction
Executes a resource action on the specified resource adapter for a resource.
updateResourceObject
unlinkResourceAccountsFromUser
validate
If an op argument is given that is not on the preceding list, a workflow service returns:
‘Unknown WorkflowServices op’
and the workflow context variable WF_ACTION_ERROR will be non-null.
Understanding the View Operation Methods
Because most workflow processing involves views, the most common view-related methods used in workflows are the checkoutView and checkinView methods. Checking out a view object will lock the underlying object such that no other user can write to it. This is especially important in workflow processing because a workflow may check out (lock) a user, and then suspend due to a manual action, leaving the user locked until the manual action is serviced (which could be hours or days later). By default, locks on objects expire in 5 minutes, which poses a second concern for workflows. A check in of an object requires that the caller already have the object locked. So a workflow that checks out a view (implicitly locking the object), suspends for 10 minutes, and the checks in the view will fail because the callers lock will have been aborted due to the 10 minute delay.
The following example shows a typical checkout operation:
Code Example 1-3
<Action id='-1' application='com.waveset.session.WorkflowServices'>
<Argument name='op' value='checkoutView'/>
<Argument name='type' value='User'/>
<Argument name='id' value='mfairfield'/>
<Variable name='view'/>
<Return from='view' to='user'/>
</Action>
Using map of options with Checkout and Checkin Calls
It can be challenging to determining which options you can use as optional arguments (which are defined as part of the UserViewConstants class) for these check out and check in calls. The Javadocs list options in this format:
OP_TARGETS
OP_RAW
OP_SKIP_ROLE_ATTRS
Instead of hard-coding these literal strings in your code when checking for options, Identity Manager provides constants that you can use throughout your code to represent a string. While this is a good coding practice, you cannot reference the static fields of UserViewConstants, such as OP_TARGET_RESOURCES, through XPRESS or workflow.
To identify valid strings that you can pass in the correct value, you can write a test rule that reveals the true string. For example, the following rule returns TargetResources.
Code Example 1-4
<block>
<set name='wf_srv'>
<new class='com.waveset.provision.WorkflowServices'/>
</set>
<script>
var wfSvc = env.get( 'wf_srv' );
var constant = wfSvc.OP_TARGETS;
constant;
</script>
</block>
Although handy for finding out a string, this rule is not appropriate for production deployment because it returns the same string for every call made to it. To minimize this problem, Identity Manager constants that are used in view processing are never changed. Once you have coded the constant in your workflow, the view's interpretation of that constant will not change from release to release.
One you have identified valid strings, you can update your checkout view call as follows. The following code checks out a view that propagates only changes to Identity Manager and Active Directory.
Code Example 1-5
<Action id='-1' application='com.waveset.session.WorkflowServices'>
<Argument name='op' value='checkoutView'/>
<Argument name='type' value='User'/>
<Argument name='id' value='mfairfield'/>
<Argument name='options'>
<map>
<s>TargetResources</s>
<list>
<s>Lighthouse</s>
<s>AD</s>
</list>
</map>
</Argument>
<Variable name='view'/>
<Return from='view' to='user'/>
</Action>
Best Practices
From a performance perspective, best practice suggests limiting the size of the User view whenever possible. A smaller view means less data is pulled from the resource and sent over the network. Because the view is held as a variable in the workflow, any time the workflow task is suspended the view must be written to the TaskInstance object. If a system is running thousands of workflows concurrently, and each workflow contains large views, the amount of time spent transferring the view to/from the repository (which includes serialization/deserialization) becomes a significant bottleneck.
The best use of a view is to carry only enough data necessary to allow changes to the user to be made and approved intelligently. If the intent of the caller is to change a user's password on a set of resources, all that is necessary to know to drive this process is a list of accounts associated with the user. Specific account data would not typically be necessary for this process.
Sample Scenario One
A customer might decide to implement a custom workflow so that users can request access to a particular resource, that workflow should check out the User view to allow a change to be submitted to it (pending the appropriate approval). In this example, the only information that probably must be available is the Identity Manager User portion of the view so that the waveset.resources list and the accountInfo object can be updated appropriately. In this situation, use the TargetResources option when checking out the User view to check out only the Identity Manager User portion of the User view with an option map similar to the following:
You can reduce the size of the User view in the WorkItem view. Work items are the objects that represent a task assigned to an individual such as an approval, a delegation, or simply an interruption in a workflow to allow a user to input additional information. Custom workflows create approvals and interact with forms through manual actions. In short, a manual action copies all Workflow variables that are in the scope of the current <ManualAction> element. In addition to the task context, into a variables object within the WorkItem object. In terms of approvals, you rarely need the full User view and context variables. As a result, consider reducing the WorkItem size by specifying the ExposedVariables argument when defining a ManualAction.
The <Exposed Variables> element tells the workflow exactly which variables are necessary to capture in the WorkItem for subsequent processing. Remember that if a single Workflow supports multiple approvers, multiple WorkItems will be created (one for each approver). 100KB here, 100KB there and pretty soon we are talking about some real memory if a workflow has 10 approvers.
Sample Scenario Two
The preceding scenario shows a relatively uncomplicated implementation of single manual action. But typical deployments involve more complicated scenarios. For example, a customer might require that when a user is created, an approval goes to a ‘bucket’, where one of approximately 25 approvers can select the approval. To mimic a bucket, you can create a work item for each approver in the bucket. All an approver must do is accept the action. Once accepted, Identity Manager can discard the remaining 24 work items, and generates the actual approval work item for the approver who accepted the bucket request.
Consider that there are a total of three buckets that act as escalation tiers. When the approval is processed through Bucket 1, Identity Manager escalates a new request into Bucket 2, and the process begins again. This process results in approximately 26 work items per bucket (25 + 1) multiplied by three (for three buckets). One user request would create 78 work items, granted not all at once. But then consider this occurring in a deployment environment containing a user base of 500,000 users with hundreds of these requests flowing in each day. Had the implementer of this scenario not bothered to size the WorkItem views by using the ExposedVariables argument, Identity Manager would store a large amount of bit of non-essential data in the work items and being passed over the JDBC connection.
Code Example 1-7
<Activity id='0' name='activity1'>
<ManualAction id='-1'>
<FormRef>
<ObjectRef type='UserForm' name='Access Review Abort Confirmation Form'/>
</FormRef>
<ExposedVariables>
<List>
<String>user.waveset.accountId</String>
<String>user.waveset.resources</String>
<String>user.accounts[Lighthouse].idmManager</String>
<String>user.accounts[Lighthouse].fullname</String>
</List>
</ExposedVariables>
<ViewVariables>
<List>
<String>user</String>
</List>
</ViewVariables>
</ManualAction>
<WorkflowEditor x='53' y='111'/>
</Activity>
Sample Scenario Three
You must write a custom user provisioning request workflow for users to execute. This type of workflow might be handy when customers want managers to submit provisioning requests for their direct reports but prefer to avoid making every manager in the organization an Identity Manager administrator.
With these requirements in mind, you create a custom workflow that:
- allows managers to create or update direct reports
- incorporates a ManualAction that allows managers to edit the checked-out view or the newly created view
- ensures that by check in, the process will have gone through (using custom manual actions), or will go through (Using out-of-the-box approval processes), the appropriate approval processes.
You will also need to refresh the view. Refreshing the view means that Identity Manager re-examines the assigned resource information and re-fetches that information from the native resources to update the User view with the latest information (if it changed since view check-out).
You can ensure that Identity Manager refreshes the view by specifying a ViewVariables element within the manual action that instructs Identity Manager which variables in the WorkItem's variables object should be treated as a view and thus refreshed when requested. See the preceding example for an example of specifying the variable user as a ViewVariable.
Enabling Workflow AuditingWorkflow auditing is similar to regular auditing, except that workflow auditing stores additional information to enable time computations. Regular auditing reports that an event occurred, but does not indicate when the event started and ended. See the Identity Manager Administration book for more information about Identity Manager auditing.
Workflow auditing operations store predefined attribute names and their values per audit event. You can use this feature to instrument a workflow by putting auditWorkflow events at the beginning and at the end of workflows, processes, and activities.
Note
When instrumenting a workflow or process, you are not permitted to put anything in an end activity. You must create a pre-end activity that performs the final auditWorkflow event, and then unconditionally transitions to the end event.
To enable workflow auditing, you add the audit attribute to a workflow or one or more of its Activities. Once the attribute is in place, activate workflow auditing by selecting the Audit entire workflow checkbox in the appropriate task template of the Administrator interface. See the chapter titled “Task Templates” in Identity Manager Administration for procedural information about turning on auditing in a task template.
In addition, you must provide an appropriate value for the following actions, which are defined in the auditconfig.xml file to allow auditWorkflow event pairings. (You can define additional actions.)
The following as an example call showing just the information the caller must provide:
<Action application=’com.waveset.session.WorkflowServices’>
<Argument name=’op’ value=’auditWorkflow’/>
<Argument name=’action’ value=’StartWorkflow’/>
</Action>
Note
Identity Manager actually stores more information than is shown in the preceding example. Continue to the next section for details.
Workflow auditing operations store predefined attribute names and their values per audit event. You can enable auditing within a workflow by adding the audit attribute (set to true) to the WFProcess element or to one or more Activity elements. Setting the attribute at the WFProcess level causes the entire workflow to be audited, while adding the attribute to individual Activity elements causes only certain activities to be audited. If the audit attribute is not set, then auditing is disabled. In addition, auditing must be enabled from within task template that calls the workflow.
What Information Is Stored and Where Is It?
By default, workflow auditing collects most of the information stored by a regular audit event, including the following attributes:
- WORKFLOW: Name of the workflow being executed
- PROCESS: Name of the current process being executed
- INSTANCEID: Unique instance ID of the workflow being executed
- ACTIVITY: Activity in which the event is being logged
- MATCH: Unique identifier within a workflow instance
- ORGANIZATION: The name of the user’s organization
These attributes are stored in the logattr table and are derived from auditableAttributesList.
Identity Manager also checks whether the workflowAuditAttrConds attribute is defined.
You can call certain activities several times within a single instance of a process or a workflow. To match the audit events for a particular activity instance, Identity Manager stores a unique identifier within a workflow instance in the logattr table.
To store additional attributes in the logattr table for a workflow, you must define a workflowAuditAttrConds list (assumed to be a list of GenericObjects). If you define an attrName attribute within the workflowAuditAttrConds list, Identity Manager pulls attrName out of the object within the code — first using attrName as the key, and then storing the attrName value. All keys and values are stored as uppercase values.
Adding ApplicationsYou can register your own Java methods so that they can be accessed from the Identity Manager IDE. To do this:
- Edit the idm/config/workflowregistry.xml file.
- Add the application definition, in a form similar to this example:
<WorkflowApplication name='Increment Counter'
class='com.waveset.util.RandomGen' op='nextInt'><ArgumentDefinition name='start' value='10'>
<Comments>Get the next counter</Comments>
</ArgumentDefinition>
</WorkflowApplication>- Restart the Identity Manager IDE.
The new application is added to the application menu.