Creating and Editing Workflows

Use the Business Process Editor to create a new workflow or edit an existing workflow. Original workflows can also be created from existing processes.

Basic Workflow How-To Tasks

The Process Editor has the following tabs:

Interface Tab	Inputs
Process Details	Specify Name, Type, and Description of the workflow. See Process Details Tab.
Process Variables	Lists the input, output, and processing variables you can use with the workflow.See Process Variables Tab.
Process Designer	To graphically represent the process, specify the actions involved in each step, and provide the evaluation conditions for moving from one step to another. See Process Designer Tab.
Process Metrics	Review statistics gathered for the process as it launches. See Process Metrics Tab.

For more information, see:

Process Details Tab

The Process Details tab contains basic information about the workflow, including:

Name – name for the workflow.

Type – the pre-defined workflow type for this workflow. IdentityIQ uses types to determine which workflows to present in the Business Process configuration list boxes. See Workflow Types for details.

Description – a description of the workflow.

Enable Monitoring – select this option to turn on metrics tracking for the workflow.

Process Variables Tab

The Process Variables tab lists variables you can use with the workflow. For most of the default processes, the variables are listed in a collapsed, advanced view. You can expand the view to show the details for each variable. Variables include:

Input variables for workflow
Output variables for workflow
Working variables used for processing a workflow

Variables are marked as Input, Required, Editable, or Output.

To delete a variable, expand the variable and click Remove.

Object	Usage
Input	Specifies that the variable is one of the arguments to the workflow, passed in when it is launched.
Output	Stores the variable in the workflow's task result to allow the user to view the progress and results of the workflow. To view the results, navigate to Setup > Tasks > Task Results.
Editable	Enables the variable to be edited in the basic view.
Required	Indicates that the variable must contain a value (non-null) when the workflow starts.
Description	A brief description of the variable and its function.

Note

The order of variable declarations can make a difference. For variables in the XML that reference other variables in their initializations, the referenced variable must be declared first.

When variables are created through the user interface, the new variables are inserted in the list above the existing variables. When the XML representation of the workflow is generated, the variables are listed in the order they were created, which is the opposite of the display order in the user interface.

Basic View

IdentityIQ has several built-in business processes that are available when you install the product. The commonly used processes are available through the Basic View which is a simplified, form-based view. The information you edit in the Basic View can be also be configured or removed using the Advanced View. The Basic View includes the following business processes:

Note

Business processes with the LCM label are part of IdentityIQ Lifecycle Manager, which is licensed separately.

Identity Update
LCM Create and Update
LCM Manage Passwords
LCM Provisioning
LCM Registration

How to Use the Basic View

Navigate to the Debug page and edit the XML of the business process.
Manually add and configure the configForm attribute to reference the form to be presented in the Basic section of process variables. See also Editing Workflow XML.

Note

If the reference exists in the business process, but the form does not, an error is displayed and you are returned to the Advanced view.

Variable Initialization

To initialize variables for the workflow, specify an initial value for the variable in this panel. For best results, use initial values for the workflow variables, rather than creating multiple process steps to initialize each variable.

There are five ways that initialization can occur:

Object	Usage
String	Assigns a literal value to the variable.
Reference	Sets the variable value through a reference to one of the other workflow process variables.
Script	Sets the variable with a Beanshell script inside the workflow.
Rule	Sets the variable by calling a Beanshell rule outside the workflow.
Call Method	Assigns the return value of a call to a compiled Java method in a workflow library to the variable.

Note

Variable values passed into the workflow through workflow arguments supersede variable initial values. Therefore, any value provided in an argument overwrites the initial value for that argument.

Timing of Variable Definition

Variables that are known at the beginning of workflow development can be defined before the graphical process design begins. Throughout the development process you might need to define other variables. Variables are not restricted to only those that were previously defined on the Process Variables tab. Variable definition can be done before, during, or after the design process.

Process Designer Tab

The majority of the work in creating and modifying a workflow is done on the Process Designer tab. The steps and transitions you create for workflow determine the workflow activities and can include the following items.

Process Steps

A workflow involves a minimum of three steps: a start step, a processing step, and a stop step or END. For best results, all workflows should contain a start and stop step and that these two steps contain no actions. Workflows can contain as many or as few processing steps as are necessary to manage the required actions. To add steps using the Process Designer, navigate to the Process Editor and click the desired step type in the Add A Step section. You can drag steps around the Process Designer grid to line them up visually in a logical progression.

To add a new step:

Click Add a Step in the left-hand column to display panel that contains available steps.

Note

Only steps associated with the process type and that exist in the Step Library are listed in the Add a Step panel.
Click and drag the desired step to a position in the process design grid.

To edit to the contents of a step:

Right-click the step icon and select Edit Step.
The step details window displays. You can:
- Record the Name and Description of the step.
- Name the Result Variable, a variable to receive the resulting value of the step action.
- Specify the Action for the step. See Action Type for details.

Action Type

Each step can take one of the types of actions listed in the following table. For any of these actions, an appropriate value must be specified or selected before the action can be saved.

For example, if Script is selected, a BeanShell script must be entered in the box. If you choose the Subprocess object, a subprocess must be selected from the list. If the value is not specified, the step is saved with no associated action. Developers who use subprocesses must write the subprocesses before they can complete the step definition of steps in the master process.

Note

Because all processing options should end with the stop step, every workflow should end with a step that transitions to Stop.

Object	Usage
Script	Executes a segment of Java BeanShell code that is included in the step.
Rule	Executes a workflow Rule -- a block of Java BeanShell code encapsulated in a reusable rule.
Subprocess	Launches another defined workflow, passing control to it until it completes. When you select this option, the list of available subprocesses -- workflows of type Subprocess -- displays and you are given the option to enable step replication.
Call Method	Calls a compiled java method in the IdentityIQ workflow library, exposed through the standard workflow handler. When you select this option, the list of available methods displays.

The Enable Monitoring flag on this window turns on metrics tracking for the step. See Process Metrics Tab for more information on process monitoring and metrics.

Script

Scripts are java BeanShell code that you write in order to execute a desired action. You write scripts directly in the Source box in the detail window for the step.

Note

The script examples in this document all show very short java BeanShell code blocks. There is no set length for a script. A script block within the XML can be any length needed to accomplish the required processing. However, long scripts are frequently encapsulated in rules, as discussed in the next section.

Rule

Rules are also blocks of java BeanShell code. Code encapsulated in a rule is available for reuse by other areas of the application that can launch a rule of the same type. Rules created through this window are of type Workflow and can be used by any workflow. When you choose Rule as the Action, you can select an existing workflow rule from the list or create a new rule in the rule editor. To open the rule editor, Click the [. . .] icon.

Subprocess

Subprocesses are other workflows. You can use subprocesses to subdivide complex processes into smaller segments that can be easily managed and reused by other workflows. Subprocesses are complete workflows that contain a start step, a stop step, and as many processing steps as are needed to complete their activities.

You can enable step replication to enable multiple subprocesses to run to completion at the same time instead of having them run serially. For example, in an approval step, you can launch multiple approval subprocesses, to multiple approvers, that can take an approval all of the way through provisioning instead of the approval step waiting for all approvals to complete before provisioning can begin.

When you enable replication, you must select an item from the main workflow for replication and an argument that is passed to the action containing the replicated item. Only one item can be replicated per step, and all of the items must be passed the same argument. A new subprocess is generated for each item replicated.

Call

The IdentityIQ workflow library contains a set of methods that you launch within a workflow. Methods are exposed through the standard workflow handler that the workflow engine calls every time an action occurs in a workflow. Every workflow has access to the methods in the standard workflow handler. Additional libraries of methods are also available to use in workflows.

Note

When no library list is specified for the workflow, the default includes access to the Identity, Role, PolicyViolation, and LCM libraries.

Through the XML, you can specify other libraries, including custom libraries for an installation. The user interface does not provide an option to manage the library list.

Note

Specifying a library list overrides the default. You must explicitly include in the library list any default libraries that contain methods the workflow needs. See Workflow Element for more details on specifying a library list.

When Call Method is selected for the workflow step, Action, the method name is selected from the Call Method list. The methods in these workflow libraries are listed and briefly described in Workflow Library Methods.

Step Arguments

When arguments need to be passed to the script, rule, subprocess, or library method launched by a step, you must specify the argument on Arguments tab for the step. Arguments can be specified in the following ways:

Type	Usage
Basic View	Some steps copied from the step library include a configuration form to simplify the specification of arguments. When a step has a configuration form, this is called the Basic View and is shown by default. The Basic View allows you to set arguments using literal values.
Advanced View	The advanced view gives you more control over how the argument values is calculated.
Return Variables	Each step can return only one result variable, which can be specified through the user interface. When a step has an action that launches a subprocess, you can also use return variables. Multiple values can then be passed back from the subprocess to the main workflow. Because the user interface does not provide a vehicle for declaring return variables, You must specify the return variables directly in the XML.

Type	Usage
String	A literal value. For example, the name of an email template to use.
Reference	A reference to one of the workflow's process variables.
Script	A segment of Java BeanShell code that returns a value.
Rule	A workflow rule that returns a value. This functions similar to Script except BeanShell is contained within a reusable rule.
Call Method	A call to a workflow library method that returns a value.

When a script, rule, or library method is used to calculate an argument value, the configuration can be more complex. If the argument definition needs data to be passed in, you can pass the data by:

Providing all the current values of workflow variables.

OR

Declaring the value of step arguments above an argument.

If desired, you can use ordered step arguments instead of workflow variables if the only use for the value is within this step.

For example, when these two step arguments are declared in this order, the method called to populate Identity_mgr can use the value in Identity_name in its processing if needed.

Argument Name	Value Type	Value Source
Identity_name	Reference	IdentityName
Identity_mgr	Rule	getManagerRule

More on Start and Stop Steps

Similar to other steps, start and stop steps can contain actions that launch scripts, rules, subprocesses, or calls to workflow library methods. By convention, these steps are included in every workflow but are used only to designate a clear starting and ending point for the workflow. These steps are generally empty steps with no action. Occasionally, debugging messages can be printed from these steps to trace workflow progress during development.

Step Icons

When steps are first added through the Process Designer, only three icon types are available: Start, Stop, and Generic Step. A variety of other icons are available. You can use different icons to make it easier to determine the actions each step performs.

To change an icon for a step:

Right-click the step icon and click Change Icon.
Select the desired icon style from the pop-up window.

Approval Steps

Approval steps are a special type of step in IdentityIQ. You can use Approvals to gather data from a user through a work item. In an approval, the user is asked to review a requested action, such as, granting a role to an identity, and then give their approval for the action to be processed.

To create a basic approval through the user interface:

Right-click the step.
Click Add Approval.

Note

A step can contain an action or an approval, but not both. Approval steps are used for approval processing. Approval steps are not used to perform other actions such as scripts, subprocesses, etc.

To edit an approval that exists in a step

Right-click the step and click Edit Approval.
Alternatively, you can choose Edit Approval from the Step Details window.

Approvals are flexible and meet a variety of business needs. An approval can be constructed many ways. approvals range from a simple one-person approval to a complex approval process that involves multiple people with different approval modes and notification schemes.

Approval Details

Every approval includes the following fields to be completed on the Details tab for the approval:

Object	Usage
Name	User-defined name for the approval.
Send	Comma-separated list of process variable names to be sent to the approval.
Return	Comma-separated list of variables names to copy from the completed approval work item back into the workflow.
Renderer	JSF (Java Server Faces) include to render the work item details. Not required if using a default renderer.
Mode	Specifies how approval is processed when multiple owners are specified.
Owner	Approver for the approval. Can be more than one Identity name and is specified by string, reference, script, rule, call method. When more than one owner is specified, mode determines how and when the item is submitted to each listed owner. Parallel, parallelPoll, and any modes submit the approval work item to all owners at the same time. Serial and serialPoll modes wait until the first owner completes the approval before submitting to the next approver in the list.
Description	Defines work item description. Shown as the work item Name in the approver's inbox. Set using string, reference, script, rule, call method.

Approval Arguments

You can set arguments to the approval on the Arguments tab. Generally, variables are passed to approval through the send list. However, any arguments that require transformation, through script, rule, or library method, must be sent through an Arg element. Args defined with reserved system names are passed through the Arg element with the reserved name specified. See Approval Steps for information on reserved system names.

Work Item Configuration

You can specify some details about the notification and escalation / reminder policy for a work item on the Work Item Configuration tab. The work item appears in the owner's IdentityIQ inbox and requires their input. If no configuration is specified, the default work item configuration is used.

To change the configuration for the work item

Select Override Work Item Configuration.
To include an electronic signature in the approval step, select Override Electronic Signature Configuration.

The following configuration options are available on the Work Item Configuration tab:

Option

Description

Initial Notification Email

To change the notification email template, select the template from the list

Escalation

Choose an escalation policy:

None -- no escalation.

Send Reminders -- allows configuration of reminder options, such as days before first reminder, frequency, email template.

Reminders then Escalation -- allows reminder option configuration plus escalation option configuration, such as reminders before escalation, escalation owner rule, escalation email.

Escalation Only -- allows configuration of escalation options, such as days before expiration, escalation owner rule, escalation email.

Child Approvals

Use Child Approvals to customize approval processing or presentation for the different sets of identities involved in the approval process. For example, a change in a user's assigned region requires someone in HR sign off and also requires manager approval. Although the approval of the user's own manager is required, any HR individual can completes the sign-off. This type of approval can be created through child approvals.

To create a child approval:

Click Add Child Approval on the Details tab for the parent approval.
Click the child approval in the Approval Children hierarchy to select it for editing.

To set up the approval described in the example, create two child approvals:

HR Approval set up – any of the identities who meet the criteria can make the decision for the group
Manager Approval set up – identity's manager specified as the owner.

Note

The reference variables HRApprovers and identityManager for the example are process variables defined with initialization scripts that retrieve the appropriate sets of Identities.

If either approval requires a custom work item configuration, you can specify the configuration on the Work Item Configuration tab for the approval. Work item configurations are inherited by child approvals if configurations are not specifically overridden for the child. If you want a single custom work item configuration for the entire set of approvals, the configuration should be specified on Work Item Configuration tab for the parent approval. In this case, the child approvals inherit the parent configuration.

Form Steps

An approval step can also display a form. Forms are a general way to request information from the user and do not necessarily represent an approval. For example, you can use forms to request a missing attribute such as the department name for an identity or ask the requester for more information about why they are making the request.

You can define a form inside the workflow step or you can reference an external form that is shared with other workflows.

To reference an existing form:

Right-click the step and click Add Form.
In the first screen, click Reference Form.
In the form reference screen, select a form from the table and select the owner who will be shown the form.

To create a custom form for gathering data from a user:

Right-click the step and click Add Form.
In the first screen, click Create.
In the form editor, specify the general form properties.

Field	Description
Description	Work item description text displayed on the user's home page.
Send	Comma-separated list of process variables to be passed as initial values for the form fields.
Return	Comma-separated list of form fields to copy back into process variables when the work item is closed.
Owner	The identity to be shown the form. Can be a simple identity name, a name stored in a process variable, or a name calculated by a script, rule, or library method.

A form includes one or more fields that define what information you want to show and the information you are asking the user to provide. This form field editor is similar to the field editor for provisioning policies and uses most of the same options.

Field Attribute	Description
Name	System-accessible name for field. Used to reference field programmatically.
Display Name	Label that is displayed on form for the field.
Help Text	Tool tip help text for field.
Type	Field type. Impacts rendering of field on form.
Multi-valued	Flag to determine if the field can contain multiple values (multi-selectable).
Read Only	Field displays a value that cannot be changed.
Hidden	Field is not displayed.
Owner	Field owner. Does not apply to form fields.
Required	Value must be entered.
Refresh Form on Change	Form is refreshed when the value for this field is changed. This field is useful when the value of a field in the form depends on the value in another field.
Display Only	Does not apply for workflow forms.
Authoritative	Does not apply for workflow forms.
Value	Literal, script, or rule to set the initial value of the field.
Allowed Values	Allowed values for the field. Displays as a dropdown list box or combo box based on the multi-valued setting.
Validation	Rule or script that validates the value of a field when the form is saved / submitted. Prevents submission if the value is not valid.
Dynamic	Delays the launch of allowed values, scripts, or rules until the field is selected, instead of launching as soon as the form loads.

The form editor also provides the option to specify buttons to include on the form.

To add a button definition:

Click Add Button.
Select the button Action and specify a behavior of the button.
Specify addition button options as described in the table below, and click Save.

Function	Description
Action	Select the action the button takes when pressed. Choose from the following actions: Next -- assimilates form data and advances to the next state, such as OK/Save/Approve/Submit functionality. Sets status of approval to Approved. Cancel -- Stops form editing, returns to previous page in the user interface, and leaves work item active. Back -- assimilates form data and returns to the previous state. Sets status of approval as Rejected and advances workflows. Refresh -- Assimilates the posted form data and regenerates the form. Not a state transition. Refresh is a redisplay of the form.
Label	Text to display on the button.
Parameter	Name of an optional value to be sent with the form fields when this button is pressed.
Read Only	Non-actionable button.
Skip Validation	Ignores the validation when the form is posted.
Value	Optional value to be sent with the form fields when this button is pressed.

During initial form specification, defined buttons and fields are listed together in the left panel in the order they are added. If some buttons were added before some fields, the button can be intermixed. On the final form, buttons are always grouped together at the end of the form. When the Form Editor is revisited later, the fields are listed together first, in the order they were created, and then the buttons follow in the order they were created.

Note

Buttons can be reordered in the XML to display in a different order on the form.

Custom forms can also be created or edited through XML. Various advanced form options, such as sections, multi-column layout, are only available through the XML. See Forms for more information.

Step Conditions

Normally when a transition is made into a step, the step action is executed. In some cases you might want the execution of the step to be optional. You can add a step condition to control whether or not the step action executes. Step conditions can also simplify transition lines in the process because you do not have to create many complex transitions to skip over steps. You can advance from one step to another and let the step conditions determine if the step is executed.

To edit the step conditions:

Right-click any process step.
Click Add Step Condition.
Specify addition button options as described in the table below, and click Save.

You can express conditions as any of the following:

Type	Description
Reference	Evaluation of a defined process variable. Must be a Boolean variable.
Script	Segment of java code that evaluates process variables.
Rule	Workflow rule that contains a reusable segment of java code to evaluate process variables.
Call Method	Call to launch a Java method in the IdentityIQ workflow library. Exposed through standard workflow handler.

Selecting the Negate option changes the evaluation to the opposite condition. For example, if the condition evaluates to False, the negate option changes it to True.

Step Transitions

Steps are connected through Transitions. Transitions can connect one step to the next sequentially. Alternatively, steps can include evaluation statements that enable conditional processing, such as certain data conditions that can cause the workflow to execute Step A versus Step B.

To add a transition do the following:

Right-click the process step for starting the transition and select Start Transition.
Navigate to the process step for ending the transition, right-click and select End Transition.
Right-click the transition icon and select Edit Transition to set the condition.
To add additional conditions to this transition, repeat the process.

To edit the transition conditions:

Right-click the transition diamond
Click Edit Transitions.
Specify addition button options as described in the table below, and click Save.

A step can have as many transitions to next steps as needed. Transition conditions are evaluated in the order they are listed. The first transition that has no condition, or whose condition evaluates to true is taken. Use the up and down arrows in the transitions dialog box to reorder the transitions. As a recommended practice, the final transition should have no condition. That transition is taken when no other transition conditions are met. If a step only has transitions with conditions, and none of the conditions are met, the workflow ends.

Conditions can be expressed as any of the following:

Type	Description
String	Not used. This condition is an artifact of the common structure used for variable setting and does not apply to conditions. A literal value of True or False can be specified but does not allow any evaluation in the transition. True always launches the associated step and False always bypasses the associated step.
Reference	Evaluation of a defined process variable. Must be a Boolean variable.
Script	Segment of java code that evaluates process variables.
Rule	Workflow rule containing reusable segment of java code to evaluate process variables.
Call Method	Call to launch a Java method in the IdentityIQ workflow library. Exposed through standard workflow handler.

Transition conditions must evaluate to Boolean values. If the value is true, the workflow moves to the step that the transition references. If the value is false, the next transition in the list is evaluated.

Selecting the Negate option changes the evaluation to the opposite condition. For example, if the condition evaluates to False, the negate option changes it to True.

Process Metrics Tab

The Process Metrics tab displays the following statistics that are useful for troubleshooting workflows:

Number of times the workflow launched
Number of times the workflow succeeded or failed
Average and maximum duration of the workflow
Date the workflow last launched

You can view additional process metrics, including data tracked at the step level, through the Intelligence > Advanced Analytics > Process Metrics Search tab.

To turn on metrics tracking:

For individual workflow steps, select Enable Monitoring in the Details window.
Alternatively, you can right-click on a step and select Enable / Disable from the dropdown menu on the step.

To turn on monitoring for all steps in a workflow, click Monitor at the bottom of the business process editor window.