Sun Java[TM] System Identity Manager 7.0 Workflows, Forms, and Views |
Chapter 1
WorkflowThis chapter describes Sun Java System Identity Manager workflow.
Topics in this Chapter
Related Chapters
- Workflow Services – Describes the workflow service methods that are available to the Identity Manager implementer who is customizing Identity Manager.
- XPRESS Language – Lists and describes use expressions written in the XPRESS language to include logic in workflows and forms.
- Introduction to the Identity Manager Integrated Development Environment in Identity Manager Deployment Tools– Introduces the Identity Manager Integrated Development Environment (IDE) and describes how to start the tool, set editor options, save, and debug 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 capability, which comprises multiple processes (workflows) that control creation, update, enabling, disabling, and deletion of user accounts.
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:
The Identity Manager Integrated Development Environment allows you to customize each of these activities.
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.
Workflow Processes
Depending upon where you are in the product interface, workflows are referred as workflows, tasks, process, or TaskDefinitions.
Task Definitions
From the Debug page of the Identity Manager Administrator interface, access workflow processes by looking at the list of TaskDefinitions. Select TaskDefinition from the Type menu adjacent to the List Objects button, then click List Objects. Identity Manager displays a list of the TaskDefinitions you have access to. When you customize a workflow, you are editing its TaskDefinition object.
The launched instance of a TaskDefinition is represented as a TaskInstance object, which you can also view from the Debug page.
Task Definition Parameters
The following table lists the standard configuration parameters.
About Manual Actions
A manual action is part of the workflow process definition that defines a manual interaction. When the workflow engine processes a manual action, a WorkItem object created in the repository. The work item must be marked "complete" before the workflow can proceed. Since most manual actions are used to solicit approvals, the work item table is under the Approvals tab.
Any manual action that belongs to a workflow is represented by a WorkItem object in the repository.
TaskInstances
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
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.
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:
Workflow ComponentsWorkflow processes represent the steps that must be followed to reach a desired goal. Processes define:
Each workflow process is defined by one or more of these components:
- 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
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 timeout 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.
<Activity name='Wait'>
<ManualAction name='approve' timeout='180'>
<Owner name='$(APPROVER)'/>
<Variable name='APPROVAL' value='false'/>
<Return from='APPROVAL' to='APPROVED'/>
<FormRef>
<ObjectRef type='UserForm' id='#ID#UserForm:ApprovalForm'/> </FormRef>
<ReportTitle>
<concat>
<s>Awaiting approval from \n</s>
<ref>APPROVER</ref>
</concat>
</ReportTitle>
</ManualAction>
<Transition to='Escalate'>
<eq>
<ref>WF_ACTION_TIMEOUT</ref>
<s>true</s>
</eq>
</Transition>
<Transition to='Approved'>
<eq>
<ref>APPROVED</ref>
<s>true</s>
</eq>
</Transition>
<Transition to='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 work items to be displayed or operated upon.
The following work item types are recognized by the system.
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.
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.
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.
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.
Workflow Task
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:
The results of this expression, if any, are displayed in the Status column when a result is pending (for example, pending (custom status)).
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 Identity Manager Audit Logging for more information about Identity Manager auditing.
Workflow auditing is enabled by adding 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.
Overview
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.
The following example enables auditing for the Notify action:
<Activity name='Notify' audit='true'>
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.
Configuring Workflow PropertiesThe System Configuration object controls workflow configuration properties. The following table lists the most frequently configured properties.
For information on using the Identity Manager Integrated Development Environment to view or edit the System Configuration object, see Introduction to the Identity Manager Integrated Development Environment in Identity Manager Deployment Tools.
Table 1-9 Workflow Properties in System Configuration Object
Attribute Name
Data Type
Default Value
consoleTrace
String
false
fileTrace
null
maxSteps
String
5000
resultTrace
String
false
retainHistory
String
false
traceAllObjects
String
false
traceLevel
String
1
validationLevel
String
CRITICAL
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 is 5000 steps.
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.
Synchronize User Password WorkflowUsed by the PasswordSync application to synchronize user passwords. Called by the JMS Listener adapter, this workflow takes each request sent by the adapter and checks out, then subsequently checks in, the Change User Password view. After the workflow has completed check-in, the workflow by default launches a confirmation email to the user, specifying whether the check-in passed or failed.
Variables
The Synchronize User Password workflow contains the following variables.
IDMAccountId
Specifies the Identity Manager Account ID that was resolved by the message mapper. Null indicates that the user was not found in Identity Manager.
password
Identifies the password that should be synchronized to all resources.
sourceResource
Identifies the name of the resource where the resources account was found in Identity Manager.
userEmail
Specifies the email address of the user. This value is derived either from Active Directory. If null, this is the email address stored in Identity Manager.
PasswordSyncThreshold
Specifies the configured number of seconds to allow before triggering synchronization. This setting ensures that passwords updated from the Identity Manager User Interface and sent to source resources will not trigger a recursive synchronization of the user's password.
lastSourcePasswordUpdate
Indicates the last time (in milliseconds) that Identity Manager updated the source resources password. This setting ensures that passwords reset from the Identity Manager User Interface and sent to a resource will not again trigger a synchronization of the user's password.
lastUpdateSecs
Indicates how many seconds ago the password was updated.
PasswordSyncResourceExcludeList
Lists the resource names that should always be excluded from synchronization. This setting can be configured by editing the System Configuration object attribute PasswordSyncResourceExcludeList.
resourceAccountId
Specifies the native accountId coming from the source resource.
Activities
checkForIDMAccountID
Checks for a null IDMAccountId. If null, transitions to an empty activity called noIDMAccountForResourceAccount. If a non-null account exists, the workflow then transitions to checkLastUpdateThreshold.
noIDMAccountForResourceAccount
Does nothing by default, but is called only if the MessageMapper did not resolve the incoming resource account ID or GUID into an Identity Manager user name.
checkLastUpdateThreshold
Confirms that the lastUpdateSecs variable is less then the PasswordSyncThreshold. This activity is used to prevent recursive password resets when a password is changed from the Identity Manager product. For example, a user changes his resource passwords, which include Active Directory. Then, the password notifier tells Identity Manager that the password had just been changed. Without this check, Identity Manager would perform an extra password change. If the passwordThreshold had been exceeded we would continue to the checkoutView activity.
CheckoutView
Checks out the ChangeUserPassword for the given Identity Manager account. If there is a successful check out, the workflow transitions to SetPasswordView. Otherwise, it transitions to NotifyFailure.
SetPasswordView
Iterates over the resource accounts and selects all resources that are not either the source resource or in the exclude list. All other resources are selected, and the expiredPassword flag is set to false to avoid the password having to be changed immediately afterwards. This activity always transitions to CheckTargets.
CheckTargets
Checks to assure we got at least one other target to synchronize. If Identity Manager does not find any other resource accounts, the workflow transitions to UnlockView.
UnlockView
Unlocks the currently checked out view and transitions to end.
CheckinView
Checks the view in, if there is a failure transitions to NotifyFailure. Otherwise, it transitions to Notify.
Notify
Notifies the end user of a successful synchronization and uses the PasswordSyncNotice email template. This activity always transitions to end.
NotifyFailure
Notifies the end user of a failure synchronization and uses the PasswordSyncNotice email template. This activity always transitions to end.