6.5 Guidelines for Creating Workflows

To create well-formed workflows, you need to understand the rules for adding activities and flow paths. In addition, you need to understand how to manipulate workflow data. See the following topics:

NOTE:You can validate a provisioning request definition before you deploy it. For more information, see Section 2.6, Validating Provisioning Objects.

6.5.1 Rules for Activities

When adding activities to a workflow, follow these rules:

  • A workflow must have only one Start activity and one Finish activity.

  • A workflow can have zero or more of the following activity types:

    • Approval activity
    • Log activity
    • Branch activity
    • Merge activity
    • Condition activity
    • Mapping activity
    • Workflow Status
    • E-Mail activity
    • Role Request
    • Start Workflow
    • Integration
    • Entitlement
    • Entity
  • Each Branch activity must have a corresponding Merge activity.

  • The Role Binding activity can only be used for workflows that support roles.

  • To ensure that the provisioning step is performed, a workflow must have at least one Entitlement activity or Entity activity.

6.5.2 Rules for Flow Paths

When adding flow paths to a workflow, follow these rules:

  • With the exception of the Start activity, all activities can have one or more incoming flow paths. The Start activity cannot have any incoming flow paths.

  • The Finish activity cannot have any outgoing flow paths.

  • There can be only one flow path out of the Start activity. The flow path type must be forward.

  • There can be between one and five flow paths out of the Approval activity. The valid flow path types are approved, denied, refused, timedout, and error. At runtime, only one of the flow paths is executed.

  • There can be only one flow path out of the Entitlement, Entity, Log, and Merge activities. The flow path type must be forward.

  • There can be two or three flow paths out of the Condition activity. The valid flow path types are true, false, and error. The true and false flow paths are required; the error flow path is optional.

  • There can be one or more flow paths out of the Branch activity. The flow path type must be forward for each path. At runtime, all of the flow paths execute.

  • Flows paths out of Role Binding activities must connect to the Finish activity.

The following table summarizes the rules for adding flow paths into and out of an activity:

Table 6-4 Number of Flow Paths Permitted for Each Activity

Activity

Inbound Paths

Outbound Paths

Start

0

1 Must always be forward.

Approval

1 to n

1 to 5 Approved, denied, refused, timedout, or error

Log

1 to n

1 Must always be forward

Branch

1 to n

1 to n

Merge

1 to n

1 Must always be forward

Condition

1 to n

2 to 3 True and false are required; error is optional

Mapping

1 to n

1

Workflow Status

1 to n

1 Must always be forward

E-Mail

1 to n

1 Must always be forward

Role Binding

1

1 Must always be forward and connect to Finish activity

Role Request

1

2 forward, error

Start Workflow

1

2 forward, error

Finish

1 to n

0

Integration

1 to n

1 to 4 Success, timedout, error, fault

Entitlement

1 to n

1 Must always be forward

Entity

1 to n

1 Must always be forward

The following table summarizes which activity types can be a source or target for each of the available flow path types:

Table 6-5 Flow Path Types Allowed for Each Activity

Activity

Forward

Approved

Denied

Refused

Timedout

True

False

Error

Success

Fault

Start

Source

 

 

 

 

 

 

 

 

 

Approval

Target

Source/Target

Source/Target

Source/Target

Source/Target

Target

Target

Source/Target

 

 

Log

Source/Target

Target

Target

Target

Target

Target

Target

Target

 

 

Branch

Source/Target

Target

Target

Target

Target

Target

Target

Target

 

 

Merge

Source/Target

Target

Target

Target

Target

Target

Target

Target

 

 

Condition

Target

Target

Target

Target

Target

Source/Target

Source/Target

Source/Target

 

 

Mapping

Source

Target

Target

Target

Target

Target

Target

Target

 

 

Workflow Status

Source/Target

 

 

 

 

 

 

 

 

 

E-Mail

Source/Target

 

 

 

 

 

 

 

 

 

Role Binding

Source/Target

Target

Target

Target

Target

 

 

Target

 

 

Role Request

Source/Target

Target

Target

Target

Target

 

 

Source/Target

 

 

Start Workflow

Source/Target

Target

Target

Target

Target

 

Source/Target

 

 

Finish

Target

Target

Target

Target

Target

Target

Target

Target

 

 

Integration

Source/Target

 

 

 

Source/Target

 

 

Source/Target

Source

Source

Entitlement

Source/Target

Target

Target

Target

Target

Target

Target

Target

 

 

Entity

Source/Target

Target

Target

Target

Target

Target

Target

Target

 

 

6.5.3 Understanding Workflow Data

When you’re creating a workflow, you can manipulate workflow data to suit the needs of your provisioning application.

Data Objects and Variables

The workflow uses a single process object to manage information about the process. A separate activity object is created for each activity in the workflow and form data is maintained for each activity that provides for user interaction.

The data objects associated with each user interface control on a form (text field, drop-down list, and so forth) can be modified immediately prior to the execution of the corresponding activity (Start activity or Approval activity). In addition, this data can be retrieved immediately after execution of the activity. After control has been passed to the next activity, the form control data is no longer available. For this reason, the workflow provides a special object called flowdata that allows you to define your own data items. You can add your own variables to this object to keep track of information that is important to your workflow, including form data that would otherwise be lost.

The following table summarizes the categories of workflow data:

Table 6-6 Categories of Workflow Data

Data Object

Lifetime

Editable

Creator

process

Workflow

No

System

activities

Workflow

No

System

activity forms

Activity

Yes

System and workflow designer

flowdata

Workflow

Yes

Workflow designer

NOTE:The workflow designer is the person who creates the workflow in Designer.

The following table describes the variables for each type of object:

Table 6-7 Data Variables in a Workflow

Object

Variable

Description

process

approvalStatus

The current status of the process.

 

category

The provisioning category (for example, Entitlements) selected by the person who initiated the request.

 

container dn

The distinguished name of the container defined for the user application at install time.

 

description

The description of the provisioning request definition.

 

group container dn

The distinguished name of the group container defined for the user application at install time.

 

id

The unique IDVault ID (CN) of the provisioning request definition.

 

initiator

The distinguished name of the person who initiated the request.

 

locale

The current locale.

 

name

The workflow process name.

 

provisioning driver dn

The distinguished name of the provisioning driver defined for the user application at install time.

 

recipient

The distinguished name of the intended target of the provisioned resource.

 

user container dn

The distinguished name of the user container defined for the user application at install time.

 

requestID

The ID for the provisioning request.

 

timestamp

The time the process was initiated.

approval-activity-name

action

The action taken by the user.

addressee

The current addressee for the approval activity.

 

name

The name of the activity.

 

timestamp

The time that the activity was queued on the work list.

 

user

The user who is associated with the current activity.

 

workId

The system generated unique ID of the current workflow activity.

form-name

custom-form-controls

Any user interface control you add to a form.

flowdata

custom-variables

Any custom variables you create to hold data needed for the workflow.

If you use one of the installed templates to create your workflow, the flowdata object can have a variable called reason, which contains text copied from the reason field on the initial request form.

You can reference these objects in ECMAScript expressions. Script expressions in a workflow can at any time refer to data items that are bound upstream in the flow. However, workflow expressions cannot refer to data items that are created downstream (because these data items don’t exist yet) or to data bound on other branches in a flow that supports parallel processing (because these branches could be executing concurrently with the current activity).

Creating New Data Items

You can create a new data item on the flowdata object by specifying a post-activity target expression on the Data Item Mapping tab for the Start or Approval activities. If you specify a name for a new data item in the Target Expression column, this automatically creates the variable. Any activity executed after this activity can then access the data item.

For example, you might want to map the form field called reason to the target expression flowdata.myReason. The variable myReason then becomes a new data item that is available to all activities executed later in the workflow.

Modifying Data Items

You can modify a data item by specifying a pre-activity expression on the Data Item Mapping tab for the Start or Approval activities. For example, to prepend a dollar sign to a price, you might map the following source expression to a target form field called Price:

"$" + flowdata.get(’cost’)

When the form displays to the user, the Price data appears as follows:

$xx.xx

Another example might be computing the total cost by adding the tax to the base cost. To do this, you could map the following source expression to a target form field called TotalCost:

Number(flowdata.get('cost')) + Number(flowdata.get('tax')) 

Working with Complex Data Item Mappings

All data in the flowdata object is maintained in XML, so you can create data items in a hierarchical fashion as well. For example, suppose you have a workflow form that allows a user to ask for access to two internal systems, one for accounts payable and one for receivables. Suppose the form has (among other fields) two Yes/No fields named Acct_Pay and Acct_Rec. In the post-activity data item mappings, you might create two mappings as follows:

Table 6-8 Complex Data Item Mapping Examples

Source Form Field

Target Expression

Acct_Pay

flowdata.SystemAccess/AcctPay

Acct_Rec

flowdata.SystemAccess/AcctRec

This would create an XML element named SystemAccess with two child elements named AcctPay and AcctRec. One reason to structure data in this way is for clearer organization and management of data in complex workflows containing many forms and data items. To retrieve data from these hierarchies, the following syntax would be used:

flowdata.get(’SystemAccess/AcctPay’)

For complete details on building ECMAScript expressions, see Section 9.0, Working with ECMA Expressions.

Moving Form Control Data to Flowdata

All form controls you create (except for DNDisplay) are automatically made available for use in pre-activity and post-activity expressions on the Data Item Mapping tab for the activity that uses the form. For example, suppose you want to make a user’s entry data in control ACONTROL on form AFORM in AACTIVITY available for use in a subsequent activity. To do this, you would select AACTIVITY in the workflow, select the Data Item Mapping tab, and click the Post Activity Mapping radio button. Next to the source form field ACONTROL, you would then enter a target expression in the following format:

flowdata.my_ACONTROL

Any subsequent activity in the workflow would then be able to access this data by using pre-activity source expressions such as these:

flowdata.get(’my_ACONTROL’)
flowdata.getObject(’my_ACONTROL’)

Moving Flowdata to Form Controls

You can also move flowdata values into form controls. The simplest case is moving a single text value into a form control. In the example above, suppose ACONTROL is a simple text entry field. In this case, to move it into another text entry field in an activity called ZACTIVITY, you would select ZACTIVITY in the workflow, select the Data Item Mapping tab, and click the Pre Activity Mapping radio button. Next to the target form field, you would then enter this source expression:

flowdata.my_ACONTROL

To move more complex form control data (for example, a MultiValue DN control) into another form control, you can use the getObject() expression syntax. For example, assuming ACONTROL is a MultiValue DN control, you could use this source expression:

flowdata.getObject(’my_ACONTROL’)

To move data into a form control, you need to be aware of type constraints. For example, you should not try to move text-based data into a numeric control, or a Boolean value into a DN control.