|
| |
| Sun Java System Identity Manager 6.0 Workflows, Forms, and Views 2005Q4M3 | |
1
Identity Manager Workflow
This chapter describes Sun Java™ System Identity Manager workflow and provides information helpful when using the Business Process Editor to create and edit workflow tasks.
Topics in this Chapter
In this chapter, you will learn about:
Related Chapters
See these 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 Business Process Editor – Introduces the Business Process Editor (BPE) and describes how to start the tool, set editor options, and save the processes you have edited. You can also use the BPE to debug 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 Business Process Editor graphical interface, you can customize each workflow launched by the Identity Manager Administrator interface.
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 of the 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 Business Process Editor (BPE) 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, 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.
Typically, when you edit and save a workflow definition, Identity Manager upgrades its TaskDefinition by:
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 objects 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. 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.
Note Identity Manager does not lock the repository while a workflow is executing. This is because workflows can run for days, and the repository cannot remain unlocked for that long. However, Identity Manager prevents you from launching another update workflow on the same user.
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:
Default Workflow ProcessesUsing the BPE, 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.
Using the Business Process EditorThe BPE application is a standalone, Swing-based Java application that provides a graphical and forms-based view of each process.
Follow these general steps when working with workflow in the BPE:
The following sections provide specific information and procedures for each of these general steps.
For guidelines on starting the BPE, setting editor options, using keyboard shortcuts, and using the BPE debugger, see Introduction to the Business Process Editor.
Loading a Workflow ProcessTo load a workflow process:
- Select File Open Repository Object from the menu bar.
Tip You can also use the Ctrl-O shortcut. For a complete list of shortcuts you can use in the BPE, see Introduction to the Business Process Editor.
- If prompted, enter the Identity Manager Configurator name and password in the displayed login dialog, and then click Login.
The BPE displays a list of items to select, which include:
- Select a workflow task or subprocess, and then click OK.
Note If you are loading a workflow process for the first time, the workflow components displayed in the right pane may not display correctly. Right-click in the right pane, and then select Layout to re-display the diagram.
Getting Around in the Business Process Editor
Before you start customizing a workflow task, you should know how to work, view and enter information, and make selections in the BPE.
The BPE interface includes a menu bar and dialogs for selections. The primary display is divided into two panes: the tree view and the diagram view.
Tree View
The tree view (in the left interface pane) shows a hierarchical view of a task, form, view, or rule. It lists each variable, activity, and subprocess in order, nesting actions and transitions under each activity.
Figure 2. BPE Tree View
Tree View Icons
Icons that display in the tree view represent the different elements of each task.
This icon…
Represents this process element…
activity
action
argument
result
return
subprocess
transition
variable
Table 1. Process Element Icons
Each of these elements is defined later in this chapter.
Diagram View
The diagram view appears in the right interface pane, and provides a graphical representation of a process. Each icon represents a particular process activity.
Repositioning Components
You can rearrange the components that display in the diagram view:
- Click and drag an icon to reposition it within the diagram.
- Right-click in the diagram view to display the actions menu, and then select Layout to automatically reposition all components in the diagram.
Notes
- Sun recommends that you use the Layout feature selectively. It is most useful when you first display a process. Often, the process does not appear completely when first displayed.
- You can set editor options so that layout is adjusted automatically when you open a workflow for the first time. For more information about setting editor options, see Introduction to the Business Process Editor.
To save your positioning for future editing sessions, select File Save to Repository, if you want to preserve your revisions in the repository.
Changing Displayed Connectors
You can select whether you want arrows to display on the lines connecting components, and the type of arrows to display. Right-click in the diagram view, and then select Arrows. Display options are None, Open, and Filled.
Menu Selections
Use the menu bar or the action (right-click) menu to work in the interface. In the tree or diagram view, click to select an item, and then right-click to display action menu selections available for that item.
Figure 3. Diagram View Component Action Menu
Workflow Dialogs
Each workflow component has an associated dialog that allows you to define the component and its actions. Some dialogs, such as the Activity dialog, displays tabs that access additional dialog pages.
Each dialog is described in detail in the following sections.
Editing Dialog Fields (Changing Field Value Type)
Some dialog fields behave differently depending on the field value type you have selected. If the value type is String, you can type text directly into the field. If the value type is Expression, Rule, or Reference, click Edit to edit the value.
Figure 4. Edit Field
To change value type, click Edit, and then click Change Type (if the current value is String); or right-click and then select Change Type (if the current value is Expression, Rule, or Reference).
Changing Display Type
In several dialogs, you can change the way information displays. For example, on the Script tab of the Actions dialog, right-click to change the default display type (Graphical) to an alternate display type.
Display types are:
- XML – Displays XPRESS or JavaScript source. You may prefer this display type if you are comfortable with XML.
Figure 5. XML Display
- Graphical – Displays a tree of expression nodes. This display type provides a structure overview.
- Property Sheet – Displays a list of properties. Some of these can be edited directly. Others may require launching another dialog. For efficiency, use this display type when creating new expressions. (You can enter expression arguments more rapidly in this view than in the graphical view.)
Figure 6. Property Sheet Display
- Functional – Displays a language similar to that used by popular spreadsheets. You might choose to use this display type if you are familiar with spreadsheet programming.
Reviewing Process Summary Details
Double-click a process to view, at a glance, the variables used by the process and all process activities. Tabs that display on the Process dialog are:
Process Tab
Use to access TaskDefinition properties for this process (including the task name) and the Report Title. It also lets you re-order variables and activities for better visual organization. (Reordering in this list does not change interpretation of the process.)
Figure 7. Process Dialog – Process Tab
Repository Tab
Use to display read-only information about the process. You can also set the organization where the task is stored.
Note Generally, workflows reside in the Top organization since you need Configurator-level privileges to edit them.
You can also change the Process Type from Main Process to Sub Process. A Main Process corresponds to a TaskDefinition object in the repository, and may appear in the Run Tasks or Schedule Tasks list. A Sub Process is stored as a configuration object and does not appear in the Run Tasks or Schedule Tasks lists. The content of a subprocess can be any expression that computes either a String or an ObjectRef. Process names can be qualified as TaskDefinition:your_task or simply your_task. If unqualified, Identity Manager first looks for configuration objects before TaskDefinition objects.
Figure 8. Process Dialog – Repository Tab
Task Definition Tab
Displays if the selected process is defined as a TaskDefinition object. (Most default Workflow processes are defined as TaskDefinition objects.)
From this area, you can specify:
- Result limit – If non-negative, specifies the number of seconds that the system will retain results after a task has completed. The default value for provisioning tasks is 3600 seconds (resultLimit='3600'), or approximately one hour. Other tasks default to 0 seconds unless the task is changed to another value. When the result limit is 0, the task is cleaned up the next time the task scheduler wakes up after the task completes, which is typically a few seconds later.
A negative value indicates the task instance will never be removed automatically. However, you can manually remove it.
- Result option – Specifies how the system treats the results of previous task executions. Options are:
- Visibility – Specifies whether this task will appear in the Run Task or Schedule Task list in the Identity Manager Administrator interface. Options are:
XML Tab
Use to view and edit the raw XML for the process. You can validate changes before clicking OK to save. You can choose to edit the XML for the entire process to edit the individual activities using the diagram view.
Figure 9. Process Dialog — XML Tab
Defining Activities
An activity is a single step in the process. Each activity can contain multiple components, including transitions, variables, and actions.
Use the Activity dialog to define its components elements. Right-click the activity to display an action menu, and then select Edit to display its dialog.
Activity Dialog
The Activity Dialog contains two tabs:
Activity Tab
Figure 10. Activity Dialog: Activity Tab
Define and access these fields from the Activity tab:
- Name – Enter a name for the activity. This name displays in the BPE and, by default, in the workflow process report that displays in the Identity Manager Administrator interface. (You can set an alternative name to display in the Administrator interface in the Report Title field.)
- Hide in Report – Select to hide this activity in the Identity Manager Administrator interface workflow status process report. While Identity Manager administrators need to see how their requests are processed and their request status in the workflow process, they do not need to see unimportant activities.
- Report Title – Define the name that will display for this activity in the Identity Manager Administrator interface workflow status process report. A report title can be defined as a String, Expression, Reference, or Rule. Click Edit on the dialog to edit the title.
- AND Join – Select to specify that the activities that transition to this activity are defined as AND joins. If you do not select this option, joins are treated as OR joins.
When you select this option, the dialog re-displays a field that allows you to define a join break, which forces an AND join to break if a certain condition is met.
For example, a join break is used in the following workflow process. If any one of three approval types (role, organization, or resource) are required but rejected by an approver, the join break specifies that the process move to the Request Rejected activity (and then to End) as soon as the one approval type is rejected, rather than wait for all three to complete.
Figure 11. Activity Dialog: Join Break
You can define a join break as an Expression, Reference, or Rule. Click Edit on the dialog to edit the join break.
For help with join breaks defined as expression, refer to the detailed information about the XPRESS language.
- AND Split – Select to specify that the activities to which this activity transitions are AND splits. (The Transitions area defines the activities to which this one transitions.) If you do not select this option, splits are treated as OR splits.
- Variables – Defines one or more variables within this activity. Double-click a variable to define its name and value.
- Actions – Defines actions associated with this activity. Double-click an action to define its type and behavior.
- Transitions – Defines the transitions from this activity to one or more activities. Double-click an item in the list to define its behavior.
Joins, splits, variables, actions, and transitions are described in detail in the following sections.
Specialized Activities: Start and End
Each process must contain activities that begin and end the process. These specialized activities are start and end.
Start Activity
The start activity should have no associated actions. It has one or more defined transitions to the next activity that begins the process.
End Activity
The end activity should have no associated actions or transitions. This ensures that the process can definitively end. The first process path that reaches this activity stops the process.
Note When the process ends, any outstanding manual actions are terminated. Outstanding application calls continue to completion, but results are ignored.
Defining Variables
You can define several types of variables that are used within a process:
- Process variables – Accessible to all activities. Process variables defined within a process display in the BPE tree view.
Any attribute associated with an Identity Manager user can be accessed through a single process variable named user. The value of this variable is the user view, a complex structure that contains all of the user attributes. You access attributes of the view by building path expressions such as user.waveset.email. See Identity Manager Views in this guide for more information.
- Activity variables – Defined within an activity. Activity variables are used solely within that activity.
To create a variable from the Activity dialog, click New. To edit a variable, double-click a variable in the list.
- Action variables – Defined within an action. Action variables are used solely by the action where they are defined. To create a variable from the Action dialog, click New in the Variables area. To edit a variable, double-click a variable in the list.
Editing Variable Details
On the Variable dialog, you can define values for the variable. Use the Value field to enter a simple string value as the initial variable value. This value can be changed by an action within the workflow. Alternatively, you can select a value type (such as Expression or Rule), and then click Edit to enter values.
Figure 12. Variable Dialog
Value types include:
- String – Simple string constant.
- List – Static list, such as an XML object list. This type is infrequently used in workflows (but used occasionally in forms).
- Expression – Complex expression.
- Reference – Simple reference to a variable.
- Rule – Simple reference to a rule.
- Map – Static map, such as an XML object map. Used rarely.
- Integer – Integer constant. Can be used to make clearer the semantics of a value. Can be specified as String. The BPE coerces the string into the correct type.
- Boolean – Boolean constant. Can be used to make clearer the semantics of a value. Can be specified as String. The BPE coerces the string into the correct type. Boolean values are specified with the strings true and false.
- XML Object – Complex object that allows you to specify any of a number of complex objects with an XML representation. Examples include EncryptedData, Date, Message, TimePeriod, and WavesetResult.
Defining Actions
Actions define the details of each activity. One activity can contain multiple actions, which are categorized as:
- Script – Typically, a short XPRESS or JavaScript program.
- Application – A call to a Java class that performs a specific action. These Java classes are registered with the workflow engine and are common to account management activities, such as sending email and creating a user.
- Subprocess – A call to another workflow process. The subprocess can be defined within the main process or a reference to an external process. The content of Subprocess can be any expression that computes either a String or an ObjectRef.
- Manual – An action that requires manual interaction before continuing to the next activity or activities.
Use the Activity dialog to manage actions. To create an action, click New. By default, actions are created as scripts.
Action Dialog
The Action dialog contains five tabs:
- Action – Displays as the default dialog view. Define and access these fields from the Action tab:
- Name – Enter a name for the action. This name displays in the BPE.
With the exception of manual actions, actions do not appear in the workflow process report that displays in the Identity Manager Administrator interface. You can select an alternative name to display in the Administrator interface for manual actions. (Do this in the Report Title field.)
Hide in Report – Select to hide this activity in the Identity Manager Administrator interface workflow status process report.
Report Title – Define the name that will display for this action in the Identity Manager Administrator interface workflow status process report. A report title can be defined as a String, Expression, Reference, or Rule. Click Edit on the dialog to edit the title.
Type – Select the action type (Script, Application, Subprocess, or Manual).
Variables – Define one or more variables for use in this activity.
Returns – Assign the resulting values to variables that can be used later by this activity or a subsequent activity.
Results – Set the Waveset Results values. These values appear on the Identity Manager Administrator interface.
- Script – Set up scripts to analyze and modify variables.
- Conditional – Set conditional statements for an action. For example, if an activity has multiple actions, you can define an expression that will cause one of the actions not to be performed if certain conditions are met.
- Iteration – Allows a single action to be called multiple times. Similar to a for loop.
- Comments – Enter information you want to remember about this action. Comments are not displayed in the process diagrams, but can be used to record information to assist workflow designers in understanding the action.
Script
A script uses XPRESS logic to evaluate items in the process and to set values. Set up scripts on the Script tab of the Action dialog. Click Validate to check for logic errors in the script.
Figure 13. Script
For example, this process includes an activity called Resources Approved. The activity contains a script that sets the value of RESOURCES_APPROVED to true, which then transitions to the End Resource Approval activity.
Application
An application supports processing for an activity. Applications use:
- Variables – Define local variables or set the values of variables passed in to the application.
- Arguments – Describe the data passed in to the application.
- Returns – Assign the resulting values to variables that can be used later.
- Results – Set the task result values. These values appear on the Identity Manager Administrator interface.
You can register your own Java methods for use in the BPE. For more information, see Adding Applications.
Subprocess
Subprocesses define activities, actions, and transitions that can be called from other activities in the process. A subprocess can be defined within the main process or a referenced from an external process. The content of subprocess can also be any expression that computes either a String or an ObjectRef. Its name can be dynamically calculated by a rule. A subprocess has its own defined start and end.
Often, subprocesses are defined and used for a set of steps that must be repeated. When you call a subprocess (in the Actions area of the Activity dialog), you pass it arguments that it processes. It then returns values that you can assign to new variables.
In the following example workflow, the Role Approval activity calls a subprocess called approval-process. This subprocess:
Manual
Manual actions are process steps that cannot be automated. They require human interaction for a process to continue.
Manual actions must have an owner (the person who is required to interact with the action). The action owner can be an Identity Manager administrator or user. You can specify an owner or define an expression that determines the owner.
In the following example, the approval process incorporates a manual action called Approve, which requires that the manual action owner (defined in the Owner field) indicate a start date for the user.
Figure 15. Manual Action (Standard Approval Workflow)
Specifying an Owner
When specifying a manual action owner, specify Identity Manager administrator owners in the form $(Owner). Specify Identity Manager user owners in the form User:$(Owner).
Specifying a Timeout
Use the Timeout field to specify a maximum amount of time that the system will wait for an administrator to complete the action. This capability is useful, for example, when implementing an escalation process whereby a request is forwarded to an alternate approver after a specified time. If the Timeout value is reached, the activity will stop, then proceed down the defined escalation path. You can find out the timeout value on the default Create User page, where it occurs in the subprocesses of the main process. Alternatively, you can create an Escalation Timeout rule.
You can enter a timeout number as a literal value, or it can be computed by an expression. If the number is positive, it indicates minutes. If negative, it indicates seconds.
If you specify a timeout for a manual action, you would typically check in your workflow to confirm that the manual action completed. You would examine the workflow because the responses, or transitions, in your workflow differs based on whether someone approved the action or whether the action timed out. In the former case, the workflow would move forward. If the latter, you would likely receive another notification and/or escalation. The workflow variable WF_ACTION_TIMEOUT will be set to true if the person did not respond in time.
Note You can also create a rule to set the timeout value. To do this:
The Form field specifies the form to present to the action owner. As an alternative to a specific form name, you could also could define an expression that logically determines the name of the form.
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 now 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.
An activity with more than one transition is a split. An activity with more than one incoming transition is a join.
Split
A split is an activity that contains two or more transitions. A split lists two or more activities in the Transitions area.
In an OR split, each condition defined for the transition is evaluated. Transitions are tested in the order listed. The first path to return TRUE is taken. With an OR split, one path (the default path) must not have any conditions associated with it. An OR split is the default split when you create two or more transitions in an activity.
Figure 16. OR Split
In an AND split, each transition path listed in the Transitions area is taken. Select AND splits on the Activity dialog.
To add a transition, click New (in the Activity dialog Transitions area), and then select a component from the list of options.
Figure 17. AND Split
Join
A join is an activity to which two or more activities transition. You do not explicitly designate an activity as a join. The transitions defined in the preceding activities define it.
By default, joins are OR joins, meaning that the first path that reaches this activity causes the next step to proceed.
You can designate an activity as an AND join. AND joins require that all paths to it complete before the next step will proceed.
In the following example process, the Check Approvals activity is an AND join. Role Approval, Organization Approval, and End Resource Approval activities all must complete before the next steps can be taken.
Figure 18. AND Join (Create User Process Check Approvals Activity)
Join Breaks
A special condition on joins are join breaks, which cause an AND join to complete if a certain condition is met.
In the following example process, the Check Approvals activity contains a join break that allows the activity to complete if any one of the Role Approval, Organization Approval, or End Resource Approval activities returns a value of FALSE. In this case, it is not the completion of a step that causes the activity to continue, but a specific condition that is met.
Figure 19. Join Break (Create User Process Check Approvals Activity)
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 BPE debugger.
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.
Saving
To save your changes to a workflow process and check it into the repository, select File Save in Repository from the menu bar.
Note You can use File Save As File to save the workflow as an XML text file. Save the file in the form Filename.xml.
Validating
You can validate changes to workflow processes at different stages of the customization process:
The BPE displays validation messages that indicate the status of the process:
Warning indicator (yellow dot) – Indicates that the process action is valid, but that the syntax style is not optimal.
Error indicator (red dot) – Indicates that the process will not run correctly. You must correct the process action.
Click an indicator to display the action it refers to. After making changes, click
Re-validate. This re-tests the process to make sure the error is corrected and checks for additional errors.
Standard WorkflowsIdentity Manager ships with standard workflows that are mapped to commonly used processes. See Default Workflow Processes for a brief introduction to these default workflows. To display and edit a default workflow
- Open the Business Process Editor (BPE). For information on using the BPE, see Introduction to the Business Process Editor in Identity Manager Deployment Tools.
- Select File > Open Repository Object > Workflow Processes. The BPE 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.
Synchronize User Password Workflow
Used 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.
lastSourcePasswordSecs
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.
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.
About the Workflow Toolbox
Use the toolbox to quickly drag-and-drop workflow activities into the BPE diagram view. Toolbox activities are divided into multiple categories. Click to display activities in each area:
To open the toolbox, right-click in the diagram view and select the toolbox option.
Default Activities
By category, these default activities are available.
Default Workflow Services
Approvals
Users
Workflow Task
Default Rename Task
<Activity name='Rename'>
<Action>
<expression>
<block>
<!-- rename in the repository -->
<invoke name='renameObject'>
<invoke name='getLighthouseContext'>
<ref>WF_CONTEXT</ref>
</invoke>
<invoke class='com.waveset.object.Type'
name='findType'>
<s>TaskInstance</s>
</invoke>
<invoke name='getId'>
<invoke name='getTask'>
<ref>WF_CONTEXT</ref>
</invoke>
</invoke>
<ref>name</ref>
<map>
<s>user</s> <ref>WF_CASE_OWNER</ref>
</map>
</invoke>
<!-- rename in memory -->
<invoke name='setName'>
<invoke name='getTask'>
<ref>WF_CONTEXT</ref>
</invoke>
<ref>name</ref>
</invoke>
</block>
</expression>
</Action>
</Activity>
This method first renames the object in the repository. The method renames the task in memory.
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>
Creating an Activity from the Toolbox
To create an activity by using the Workflow Toolbox:
- Click and hold the activity you want to create from one of the four Toolbox areas (Workflow Services, Approvals, Users, Workflow Task).
Note The activity does not use highlighting to indicate that it is currently selected.
- Drag the mouse cursor into the Workflow diagram view. The activity appears in the view.
Tip Any activities you create after the first one are numbered. Renumber similar activities before creating more than two.
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:
<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)).
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=”true” attribute 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.
Sample Workflow CustomizationThe following sample illustrates the end-to-end steps you would follow to customize a a workflow process.
Example: Email Notification – This two-part example shows how to:
- Part 1 – Create an Identity Manager email template
- Part 2 – Customize the workflow process to use the new template and send email notification to a user that welcomes him to the company
Notes:
- The process illustrations included in these examples may differ slightly from those you see when you load a process. Discrepancies can result in different component positioning or the selective removal of process actions that are unimportant to the example.
- You can perform many steps from the tree view or the diagram view in the BPE. The example shows primarily how to perform tasks from the tree view.
Example: Email NotificationGoal: Customize the Identity Manager Create User workflow to send a welcome email to an approved user.
Part I – Create an Identity Manager Email Template
To create a custom email template, use an existing template and modify it. Follow these steps:
Step 1: Select the Email Template Object from the Repository
The BPE displays the email template.
Step 2: Clone the Email Template
Use the copy-and-paste function in the BPE list view to create the new template:
A copy of the email template appears in the list view.
Tip When pasting, be sure the mouse does not cover an item and that no items are selected (otherwise, the paste action is ignored).
Step 3: Rename the New Template
Step 4: Modify the Template Contents
Modify the subject and email body of the newly created User Creation Notification template as desired. You can also add a comma-separated list of either Identity Manager accounts or email addresses to the Cc field. Click OK.
Figure 23. Email Notification Part 1, Step 4
(Customize User Creation Notification Email Template)Step 5: Save and Check in the Template
To save and check the template into the repository, select File Save in Repository from the menu bar.
Part 2 – Customize the Workflow Process
Continue with Part 2, in which you modify the Create User workflow process to use the new email template.
Step 1: Load the Workflow Process
The Create User workflow appears.
Step 2: Add an Activity Named Email User
- In the tree view, select the Create User process.
- Right-click, and then select New Activity.
The tree view displays a new activity named activity1 at the bottom of the list of activities.
- Double-click activity1 to open the activity dialog.
Figure 25. Email Notification Part 2, Step 2 (Create and Name an Activity)
- In the dialog Name field, change the name to Email User.
- Click OK to save the name and close the dialog.
Step 3: Create and Modify Transitions
To include the new step in the workflow, you must add and change transitions. In the default Create User workflow, the step that notifies the account requestor that the account was created (Notify) transitions directly to end. You will delete this transition and create transitions (between Notify and Email User, and from Email User to end) to send email to the user before the process ends.
To do this:
- Right-click Notify, and then select Edit.
- In the Activity dialog Transitions area, select end, and then click Delete to delete that transition.
- In the Transitions area, click New to add a transition and open the Transition dialog.
- Select Email User from the list, and then click OK.
Figure 26. Email Notification Part 2, Step 3 (Create and Modify Transitions)
- Click OK to close the dialog.
- In the tree view, right-click Email User, and then select
New Transition to create a transition and open the Transition dialog.- Select end, and then click OK.
Step 4: Create an Action
Create an action for the new Email User activity that defines the email action and its recipient.
- In the tree view, right-click Email User, and then select New Action to create an action and display the Action dialog.
- For Type, select the Applications option.
- Enter a name for the new action.
- For Application, select email from the list of options.
Figure 27. Email Notification Part 2, Step 4 (Create an Action)
The Action dialog displays new selections in the Arguments area.
- For template, enter the new email template name (User Creation Notification).
- For toAddress, enter a variable for the user as $(user.waveset.email).
- Click New to add an argument. Name the argument accountId and enter a value for the argument as $(accountId).
Figure 28. Email Notification Part 2, Step 4 (Create an Action)
- Click OK.
Step 5: Save and Check in the Modified Workflow
To save the process and check it back into the repository, select File Save in Repository from the menu bar.
Step 6: Test the New Process
After saving, you can test the new process by using Identity Manager to create a user. For simplicity and speed, do not select approvers or resources for the user. Use your email address (or one that you can access) so that, upon creation, you can verify receipt of the new welcome message.
Adding ApplicationsYou can register your own Java methods so that they can be accessed from the BPE. 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 BPE.
The new application is added to the application menu.
Integrating Remedy with WorkflowWorkflow processes can be integrated with a Remedy server through the Remedy Resource adapter. The Remedy adapter is a gateway-based adapter that runs on a Windows platform.
Prerequisite
Confirm that you have successfully configured the Remedy resource adapter by creating a Remedy resource. To confirm that the adapter has been successfully configured, check Configure Managed Resources through the Identity Manager Administrator interface.
What Does a Remedy Schema Represent?
Schemas correspond to objects such as trouble tickets and service requests. These schemas are not configured in the adapter through the Identity Manager administrator interface, specifically the Remedy Ticket Integration. They are invoked through the workflow subprocess Configuration:RemedyTicketServices.
This section discusses the creation of Remedy tickets through Identity Manager workflow.
Creating a Remedy Integration Template
To define a Remedy template, select Configure Remedy Configuration. You then select the Remedy schema and resource.
Once the Remedy RA is defined, you define Remedy Integration templates through the Configure menu on the Identity Manager administrator interface. These templates are referenced in workflow and are used for opening and updating Remedy trouble tickets. Although the schema typically varies from customer to customer, the Remedy Integration tool is an excellent mechanism for verifying the existence of a particular schema definition and for retrieving information such as field names, field IDs, and drop-down lists of acceptable values.
Template Attributes
Remedy Template attributes are described below:
You define and modify the configuration object at the Remedy Integration configuration page in the Identity Manager Administrator interface. The RemedyTemplate works similar to an e-mail template in that it allows replacement of variables at runtime. The typical convention of $(someAttribute) is used similar to email templates. However, in the case of Remedy Templates, the system attempts to resolve variables in three different ways, in the following order:
Creating a Template
To create a template
You can then use the integration template to test the creation of objects of a particular schema by hard-coding the field values in the template for required fields and selecting Test.
Order of Variable Resolution
Integration template variables are resolved in the following order:
- Workflow context. The workflow context is automatically available to the RemedyTicketServices WorkflowApplication. During variable resolution (denoted with the $() syntax in the Remedy Integration template), the workflow context variables map are searched. For example, $(user.accounts[Lighthouse].fullname) would be valid during the standard provisioning workflow.
- Action arguments. Arguments to the RemedyTicketServices workflow application are then examined for variables that are not resolved from the workflow context.
- User-supplied value map. If a value map is specified as the value of the remedyTicketValueMap, this value map is then searched.
Additionally, static values that are specified directly in the Remedy Integration template (not denoted with the $() syntax) are assimilated directly into all requests.
Note One special argument value called TRAVERSE_RESULT. If specified, this class replaces the value with a String version of any errors in the current case waveset result. You can configure the RemedyTemplates from the Identity Manager user interface at the Remedy Integration configuration page. For example, specifying $(TRAVERSE_RESULT) as the value to the worklog field logs the current case errors.
Populating Remedy Template Fields
There are two mechanisms for populating fields in Remedy templates that are generated as result of a workflow:
Using the Remedy Workflow Process to Populate Template Fields
The Remedy Workflow Process subprocess provides access to the RemedyTicketServices Workflow application. As a Configuration object in Identity Manager (identified by id=’#ID#Configuration:RemedyTicketServices), the subprocess can be called from any point in workflow. This is especially convenient under the following circumstances:
- additional logic that is specific to Remedy is required in constructing trouble ticket requests
- you do not want the logic duplicated across workflows definitions
Note When using the Remedy Workflow Process, note that you cannot specify argument values explicitly to the application without modifying this workflow. Only variables named as arguments to the RemedyTicketServices application are defined as inputs to the subprocess. Remedy Template values are passed to the Remedy Workflow Process either through top-level variables declared (and set) in the calling process or through the remedyTicketValueMap passed as an argument to the Remedy Workflow process.
The Remedy Workflow Process process wraps the call to this application to streamline the workflow implementation. The process returns the ticketId variable, which can be used later in the workflow, if necessary.
<Activity name='openTicket'>
<Action id='0' name='RemedyTicketServices'>
</ReportTitle>
<Variable name='op' value='open'/>
<Variable name='remedyTemplate' value='OpenTicketTemplate'/>
<Variable name='ticketId'/>
<Return from='ticketId' to='ticketId'/>
<ExternalProcess>
<ObjectRef type='Configuration' id='#ID#Configuration:RemedyTicketServices' name='Remedy Workflow Process'/>
</ExternalProcess>
</Action>
<Transition to='end'/>
</Activity>
Using the RemedyTicketServices Workflow to Populate Template Fields
You open and update trouble ticket objects through workflow. The RemedyTicketServices workflow application is provided as the interface for generating requests into Remedy. The following sample provides syntax for invoking this application:
<Action id='0' application='com.waveset.helpdesk.RemedyTicketServices'>
<Argument name='op' value='update'/>
<Argument name='remedyTemplate' value='RemedyIntegrationTemplateName'/>
<Argument name='remedyTicketValueMap'>
<map>
<s>key1</s>
<ref>value1</ref>
<s>key2</s>
<ref>value2</ref>
</map>
</Argument>
<Argument name='remedyResource' value='RemedyResourceName'/>
<Argument name='ticketId' value='$(ticketId)'/>
</Action>
The RemedyTicketServices workflow also retrieves information out of the workflow context of the calling process to resolve variables identified in the Remedy Integration template.
Supported Arguments for RemedyTicketServices
The following table describes the options that the RemedyTicketServices application can take.
Configuring Workflow PropertiesThe System Configuration object controls workflow configuration properties. The following table lists the most frequently configured properties.
For information on using the Business Process Editor to view or edit the System Configuration object, see Working with Generic and Configuration Objects in Introduction to the Business Process Editor.
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. To override the default setting on a per-workflow basis, set a new value in the Maximum transitions field of the Business Process Editor Process dialog.
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.
