Chapter 1 Workflow

This chapter describes Sun Identity Manager workflow. It provides information about the following topics:

• Understanding Workflow

• Workflow Process Components Overview

• Default Workflow Processes

• Updating a Process for Identity Manager Use

• Standard Workflows

• Customizing a Process

• Configuring Workflow Properties

• Using Workflow Services

• Enabling Workflow Auditing

• Adding Applications

To better understand a typical workflow, use the Identity Manager IDE plug-in to view, run, and debug sample workflows. Instructions for installing and configuring the Identity Manager IDE are provided on https://identitymanageride.dev.java.net.

Understanding Workflow

Identity Manager workflow defines a sequence of actions and tasks that are performed consistently according to a defined rule set. Using the Sun Identity Manager Integrated Development Environment (Identity Manager IDE) graphical interface, you can customize each workflow launched by Identity Manager.

Before working with workflow, develop an understanding of:

• General workflow concepts

• How workflow is used in Identity Manager

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:

• Check password policies

• Send email to approvers

• Evaluate the results of each approval

• Create user accounts

• Create audit records

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.

Identity Manager does not lock the repository object (that is, the User) while a workflow is executing. This is because workflows can run for days, and the repository object cannot remain unlocked for that long. However, Identity Manager prevents you from launching another update workflow on the same user.

Task Definitions and Task Instances

The launched instance of a TaskDefinition is represented as a TaskInstance object. You can view both object types from the Debug page.

To Access Task Definitions or Task Instances

1. From the Debug page of the Identity Manager Administrator Interface, select TaskDefinition from the Type menu adjacent to the List Objects button

2. Click List Objects. Identity Manager displays a list of the available object types that you have access to.

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

1. Click the Manage Tasks tab in the Identity Manager Administrator Interface.

2. Select View All Tasks.

3. Select the suspended TaskInstance, then click Terminate.

Task Definition Parameters

The following table lists the standard configuration parameters.

Using the Variable Element

Identity Manager assigns a scope to all <Variable> elements when the element is declared. If you do not assign a value to the scope attribute, Identity Manager assigns it a value of local, which means that the variable can be accessed only within the XPRESS section that it is declared in.

Additional Variable attributes that define scope include:

• input – Declares that the <Variable> element has local scope and that the value can be initialized by the caller.

• output – Declares that the <Variable> element has local scope but can be returned to the caller.

• external – Declares that the <Variable> element has non-local scope – that is, assignments to this variable will result in assignment to this variable in the scope it was first declared in.

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:

• Interpreting the process definition

• Creating process instances and managing their execution

• Navigating between activities and creating work items for their processing

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.

Workflow Process Components Overview

Each 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:

  • OR Split– Tests each transition path. The first path with a value of TRUE is taken.

  • AND Split– Takes each transition path.

  Join– Defines the movement from multiple activities to a single activity. Join components are further defined as:

  • OR Join– Specifies that the first path to complete causes the next activity to begin.

  • AND Join– Specifies that the next activity cannot begin until all paths are complete.

  Subprocess– Defines a set of activities, actions, and transitions that can be called from other activities in the process.

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 Processes

Using the Sun Java System 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.

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

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:

• complete (WorkItem attribute)

• variables.* (task variables)

• variables.<view>.accounts[*].*

• variables.<view>.waveset.*

• variables.<view>.accountInfo.*

• :display.session (session for Owner)

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:

To Restrict Administrative View Capabilities

1. Define new authorization types that extend the WorkItem type. For example, define the RoleApproval type.

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

3. Assign the Role Approver capability to an administrator rather than the general Approver capability

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

  • accountId– Specifies the name of the user for whom you want to get delegation information

  • accountIdList– Lists the user names for whom you want to get delegation information.

• 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 Use

If 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 Sun Java System Identity Manager IDE 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.

To Edit a Workflow in Production

1. Rename the current TaskDefinition to include a time stamp. For example, to modify the Create User workflow, rename the TaskDefinition from Create User to Create User 20080701. You can rename a workflow TaskDefinition with the Sun Java System Identity Manager IDE.

2. Save and import the edited workflow.

   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 Workflows

Identity 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

1. Open the Sun Java System Identity Manager IDE.

2. Select File > Open Repository Object > Workflow Processes. The Sun Java System Identity Manager IDE displays the Workflow Processes list, which contains the standard workflow processes and any custom workflows in your deployment.

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

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

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.

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>

Using the Handle Native Change To Account Attributes Workflow

Whenever Identity Manager detects a native change (that is, a change not performed through the Identity Manager) to the values of an auditable attribute of a resource account, it responds by running the handleNativeChangeToAccountAttributes workflow. This workflow is associated with this System Configuration object attribute:

<Attribute name='process'>
   <Object>
     <Attribute name='handleNativeChangeToAccountAttributes' value='Audit Native
                      Change To Account Attributes'/>
   </Object>
</Attribute>

This workflow logs the native change events to the event log if you have enabled the Changes Outside Lighthouse audit filter. Otherwise, Identity Manager ignores the event. Warning: Be careful which methods you call from any workflow that replaces the default workflow listed above.

Because Identity Manager launches this workflow whenever a resource account fetch reveals a native change, it must not invoke any method or workflow that would trigger another fetch of the same resource account. For example, an infinite loop will result if you call any workflow services method that assembles the User view: getView(User), checkoutView(User), and possibly checkinView(User).

The fact that Identity Manager handles each native change by running a workflow allows you to hook the native change event, and to handle that native change however you see fit by replacing or adding to the default native change workflow. For example, you might choose to send email to an administrator or a user, to record the event in a database, to queue an update that would back out the native change, or even to pull that native change into Identity Manager and push it back out to the other resources.

Specifying the Administrator for a Source Adapter Task

You can assign a subject or administrator to a Source adapter task and designate the server on which it runs by editing the sources.subject and sources.host attributes of the System Configuration object. For more information, see Editing the System Configuration object in Deployment Guide.

Implementing the Identity Manager Whitelist Feature

You can use the whitelist feature to check forms and workflows that use the SaveNoValidate action against a list of IDs or form names. Identity Manager checks the whitelist for either form names or form-owner IDs. The list of IDs, called saveNoValidateAllowedFormsAndWorkflows, is located in the security attribute in the System Configuration object. If the form name or owner ID is on the whitelist, the form or workflow can use the SaveNoValidate action. If the form name or the owner ID is not on the list, the form or workflow is processed using a Save action. If the list is not present, all forms and workflows can be processed as SaveNoValidate.

To implement this feature in your deployment, you must add any forms or workflows using SaveNoValidate to the saveNovalidateAllowedFormsAndWorflows list in the System Configuration object. To see the IDs or form names that you must add, check the syslog or turn trace level 4 on for com.waveset.ui.util.GenericEditForm and submit any custom forms or workflows that use SaveNoValidate. Identity Manager will log a warning including the ID. If you are getting “null” form names in the syslog, confirm that the form in the TaskDefinition that was run has a name attribute.

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

Configuring Workflow Properties

The System Configuration object controls workflow configuration properties. The following table lists the most frequently configured properties.

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 System Configuration 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:

• a per-account workflow requires 30 seconds on average to complete

• the value of maxRetries is 3

• the value of lockwaitThreshold is 5000

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 Services

Identity 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:

• Understanding Method Context

• Built-In Workflow Variables

• General Session Workflow Services

• Provision Workflow Services

• Understanding the View Operation Methods

• Best Practices

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

Built-In Workflow 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.

Workflow variables are case-sensitive. For example, WF_ACTION_ERROR is not the same as wf_action_error.

General Session Workflow Services

The com.waveset.session.WorkflowServices class contains a set of services that support a range of operations, including general operations (get, checkout, checkin, etc.) on views and objects.

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.

Supported Session Workflow Services

The com.waveset.session.WorkflowServicesJavadoc for workflow services documents the internal Identity Manager Java string fields rather than the nomenclature required by XPRESS. For example, the documentation for the workflow services operation addDeferredTask is provided by the Javadoc for the WorkflowServices OP_ADD_DEFERRED_TASK string field. In general, to find the Javadoc for an operation, take the operation name, capitalize and separate with an underscore the words making the operation name, and prefix the result with the OP_. Operation argument names are treated similarly, but prefixed with ARG_.

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 provision services is to give workflows access to the Provisioner, 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 supported workflow services will have a variable number of required and optional arguments.

Supported Provision Workflow Services

The com.waveset.provision.WorkflowServices Javadoc contains information about currently supported provision workflow services. The op argument to the workflow services call must be one of these values.

If an unsupported op argument is given, a workflow service returns:

”Unknown WorkflowServices op’

and the workflow context variable WF_ACTION_ERROR will be non-null. Provision and session workflow services map XPRESS operations to argument names in the same way.

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:

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

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

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

<map>
   <s>TargetResources</s>
   <list>
      <s>Lighthouse</s>
   </list>
</map>

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, Identity Manager will create multiple work items (one for each approver).

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.

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

Using WorkItem Variables: Summary

As you can see from the preceding scenarios, you can control the size of WorkItem objects through the careful use of top-level variables. Identity Manager creates a WorkItem object for each manual action that is processed in a workflow. By default, these objects contain a copy of all top level variables from the executing workflow. There are three ways to control the variables that are passed into and assimilated back from WorkItem objects:

• ExposedVariables

• EditableVariables

• ViewVariables

ExposedVariables

You can use ExposedVariables to control which variables from the workflow are copied into the WorkItem object. If you have defined ExposedVariables, only those variables in the list are copied to the WorkItem. Using this option controls the size of WorkItem objects reducing memory usage, database size, and CPU processing time. The definition should be a list containing string representations of the workflow variables. Two example definitions follow.

<!-- Pass the entire view object but no other WF variables -->
<ExposedVariables>
  <List>
     <String>userView</String>
  </List>
</ExposedVariables>


<!-- More optimized to only pass the Lighthouse attributes and 
     email value -->
<!-- Note the definition of a partial GenericObject path and a complete 
     GenericObject path -->
<ExposedVariables>
   <List>
     <String>userView.accounts[Lighthouse]</String>
     <String>userView.waveset.email</String>
     <String>managerFlag</String>
   </List>
</ExposedVariables>

Passing only the data that the UserForm requires to operate optimizes the WorkItem processing time. This reduces the time required when processing the workItemEdit.jsp and also reduces total memory consumption and GC activities for the JVM. Without this option, the system can quickly consume a large amount of CPU time during concurrent user operations.

EditableVariables

You can use EditableVariables to control which variables from the WorkItem object are assimilated back into the workflow. The classic usage of this definition is to control which variables can be edited by the approver. EditableVariables is most useful during parallel approvals to prevent two approvers from overwriting the same data. Make sure you read the note regarding ExposedVariables.

<ExposedVariables>
<List>
   <String>userView.accounts[Lighthouse]</String>
   <String>userView.waveset.email</String>
</List>
</ExposedVariables>
<!-- Only the firstname, lastname fields should be assimilated 
     from the WorkItem -->
<-- Note the inclusion of the formButton variable which is used to 
    store the button value -->
<EditableVariables>
<List>
   <String>userView.accounts[Lighthouse].firstname</String>
   <String>userView.accounts[Lighthouse].lastname</String>
   <String>formButton</String>
</List>
</EditableVariables>

<Field button='true'>
   <Display class='Button'>
      <Property name='name' value='variables.formButton'/>
      <Property name='label' value='Submit'/>
      <Property name='command' value='Save'/>
      <Property name='value' value='submit'/>
   </Display>
</Field>

To debug, see workflow.fileTrace attribute of the System Configuration object to identify which variables are being assimilated back into Workflow from the view. ViewVariables is used to control which variables represent view objects which should be refreshed when a refreshView operation is executed from the workItemEdit.jsp page. In general a refreshView operation reloads the view data from all of its sources such as resource adapters.

ViewVariables

You can use ViewVariables to control which variables represent view objects that should be refreshed when a refreshView operation is executed from the workItemEdit.jsp page. In general, a refreshView operation reloads the view data from all of its sources such as resource adapters.

<!-- The userView variable should be refreshed during a refreshView -->
<ViewVariables>
   <List>
      <String>userView</String>
   </List>
</ViewVariables>

Use ViewVariables only when absolutely necessary for correct form and user interaction. This is option is seldom used.

Enabling Workflow Auditing

Workflow 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 Business Administrator's Guide 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.

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 Business Administrator's Guide 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.)

• StartWorkflow

• EndWorkflow

• StartProcess

• EndProcess

• StartActivity

• EndActivity

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>

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:

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 Applications

You can register your own Java methods so that they can be accessed from the Sun Java System Identity Manager IDE.

To Register Methods

1. Edit the idm/config/workflowregistry.xml file.

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

3. Restart the Sun Java System Identity Manager IDE.

   The new application is added to the application menu.