8.2 Approval Activity

The Approval activity is a user-facing activity that displays an approval form to the user. On the approval form, the user can approve, deny, or refuse a provisioning request. The Approval activity can have multiple outgoing flow paths, but only one of the paths is executed at runtime.

You can customize the approval form to suit your application requirements. For details on customizing forms, see Section 6.0, Creating Forms for a Provisioning Request Definition.

Before displaying the form to the user, the Approval activity performs any pre-activity data mappings specified for the activity.

After the user submits the form, the Approval activity performs any post-activity mappings specified for the activity. These mappings typically include copying data from form fields into the flowdata object.

8.2.1 Properties

The Approval activity has the following properties:

Table 8-3 Approval Activity Properties

Property Name

Description

Name

Provides a name for the activity.

Addressee

Specifies a dynamic expression that identifies the addressee for the activity. The addressee is determined at runtime, based on how the expression is evaluated.

For more information about developing valid Addressee expressions, and about how Addressee interacts with the Approver Type property, see Section 7.5, Addressing an Approval Activity.

HINT:To simplify the process of testing a new workflow, you can set the addressee to be the recipient. This removes the need to log out of the User Application and log in again as a manager each time you want to test your forms. This technique is particularly useful when the workflow involves multiple levels of approval. After the testing phase is complete, you can change the addressee to the correct value.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Section 4.3.3, Understanding Workflow Data.

Reminder Start

Specifies a dynamic expression that defines, in milliseconds, the time at which the first reminder e-mail should be sent. The start value is an offset from the time of the first assignment associated with the activity. You can pick predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Variables pane of the ECMA expression builder.

This is part of the reminder e-mail function. If this activity is considered important and needs to be acted on quickly, you can configure the activity to send a reminder e-mail to the activity addressee. For example, you can set the reminder settings to send a reminder e-mail 5 days before the activity times out, and on a daily basis until the activity times out. To do this, specify a Reminder Start time, a Reminder Interval, and the e-mail to be sent (see Section 8.2.3, E-Mail Notification).

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Section 4.3.3, Understanding Workflow Data.

Reminder Interval

Specifies a dynamic expression that defines the interval between which reminder e-mails are sent. You can pick predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Variables pane of the ECMA expression builder.

Escalation Addressee

Not available when the approver type is Multiple or Quorum

Specifies a dynamic expression that identifies the user who should get this task if the timeout limit has been reached.

The escalation addressee is determined at runtime, based on how the expression is evaluated.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Section 4.3.3, Understanding Workflow Data.

Escalation Count

Not available when the approver type is Multiple or Quorum.

Specifies the number of times to retry the activity in the event of a timeout.

When an activity times out, the workflow process can try to complete the activity again, depending on the escalation count specified for the activity. With each retry, the workflow process can escalate the activity to another user. In this case, the activity is reassigned to another user (the user’s manager, for example) to give this user an opportunity to finish the work of the activity. If the last retry times out, the activity can be marked as approved, denied, refused, timedout, or in error, depending on the final timeout action specified for the activity.

The Timeout interval (see Timeout in this table) takes precedence over the Escalation Interval. For example, if you set the timeout to 10 minutes, and specify an Escalation Count of 3 and Escalation Interval of 5 minutes, the activity finishes after 10 minutes without attempting all of the retries. In this example, the second retry would be canceled, and the workflow would finish processing for the activity. At the conclusion of the activity, the workflow engine would follow the link defined by the final timeout action.

Escalation Interval

Not available when approver type is Multiple or Quorum.

Specifies a dynamic expression that defines the period of time allotted for the addressee to complete the task. The escalation interval applies each time the activity is executed by the addressee.

The Timeout interval (see Timeout in this table) takes precedence over the Escalation Interval. For example, if you set the timeout to 10 minutes, and specify an Escalation Count of 3 and Escalation Interval of 5 minutes, the activity will finish after 10 minutes without attempting all of the retries. In this example, the second retry would be canceled, and the workflow would finish processing for the activity. At the conclusion of the activity, the workflow engine would follow the link defined by the final timeout action.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Section 4.3.3, Understanding Workflow Data.

Escalation Reminder Start

Not available when the approver type is Multiple or Quorum.

Specifies a dynamic expression that defines the time at which the first reminder e-mail (see Reminder Start in this table) should be sent to the Escalation Addressee. The start value is an offset from the time of the escalation assignment. You can pick predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Variables pane of the ECMA expression builder.

Escalation Reminder Interval

Not available when the approver type is Multiple or Quorum.

Specifies a dynamic expression that defines how often messages are sent to the Escalation Addressee after the first escalation reminder is sent. You can pick predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Variables pane of the ECMA expression builder.

Final Timeout Action

Determines the final state of the request in the event that the workflow times out. The choices are

  • approved

  • denied

  • refused

  • timedout

  • error

Timeout

Specifies a dynamic expression that defines the period of time allotted for the addressee to complete the task. The timeout interval applies each time the activity is executed by the addressee.

The Timeout setting takes precedence over the Escalation Count and Escalation Interval values. If the Timeout setting for the activity is reached before one or more of the escalation attempts have been tried, the activity finishes processing without executing these escalation attempts. For example, if you set the timeout to 10 minutes, and specify an Escalation Count of 3 and Escalation Interval of 5 minutes, the activity finishes after 10 minutes without attempting all of the escalation attempts. In this example, the second escalation attempt would be canceled, and the workflow would finish processing for the activity. At the conclusion of the activity, the workflow engine would follow the link defined by the final timeout action.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Section 4.3.3, Understanding Workflow Data.

Time Units

Determines the unit of measure used for the timeout interval. The choices are

  • Milliseconds

  • Days

  • Hours

  • Minutes

  • Seconds

Form

Specifies the name of the approval form to display at runtime, or lets you define a new form. Select the name of the form you want to use or create new form. When you choose to create a new form, the Create New Form Wizard launches and looks similar to this.

Select the data items to include in the form from the data items listed, then click Finish. The Approval Form Wizard generates each of the selected data items as a String type field in the new form.

An Approval activity must have a form associated with it. If no form is specified, an error message is displayed at runtime.

Exclude Requestor

Specifies whether requestors can approve their own provisioning requests. Select True to allow a requestor to approve their own provisioning requests; otherwise, select False.

Approver Type

Specifies the number of addresses that are allowed and the approval pattern that is enforced for this activity. The choices are

  • Normal: Action by the addressee is required to complete the approval.

  • Group: Action by one addressee in the group is required to complete the approval.

  • Multiple: Action by all of the addressees is required to complete the approval.

    You cannot use post activity data item mapping with the Multiple Approver Type.

  • Quorum: Action by a percentage of addressees or an absolute number of addressees (see Quorum property in this table) is required to complete the approval.

    You cannot use post-activity data item mapping with the Quorum Approver Type.

For information about how the Approver Type property interacts with the Addressee property, see Section 7.5, Addressing an Approval Activity.

Notify by E-Mail

Specifies whether this activity should send e-mail notifications. Set to True to notify by e-mail; otherwise, set to False.

You specify the e-mail to send using the E-Mail Notification tab (see Section 8.2.3, E-Mail Notification).

To use this feature, the Notify participants by E-Mail parameter for the provisioning request definition must be set to True (see Table 5-1, Overview Properties).

Quorum

Not available when approver type is Normal, Group, or Multiple.

Allows you to specify a constant value or to create an ECMA expression that specifies a percentage (for example, ’75%’) of approvals that is required before a quorum is achieved, or an absolute number (for example, ’3’) of approvals that are required before a quorum is achieved.

Digital Signature Type

See Digital Signature Type in Table 7-10.

Priority

Specifies a dynamic expression that defines the priority of the approval activity. Valid priority values are 1, 2, or 3. You can also define an expression to determine the priority from workflow data. For example, flowdata.get("Priority").

In the User Application, users can sort the list of tasks by the priority values of the tasks.

NOTE:To enable delegation to a group DN, you can have an approver type of Group or Normal, but the Addressee value must be an expression that returns the user DNs for each member of that group For example, IDVault.get(groupdn, ‘sales’, ‘members’)

8.2.2 Data Item Mapping

To bind the data items associated with the Approval activity, you define pre-activity and post-activity mappings. The pre-activity mappings initialize data in the approval form with constants, values retrieved from the flowdata object, system process variables, system activity variables, and data retrieved via expression calls to the directory abstraction layer. The post-activity mappings move form data back into the flowdata object.

Table 8-4 Approval Activity Data Item Mappings

Setting

Description

Pre Activity

Allows you to specify one or more pre-activity mappings. When this option is selected, you can double-click a cell in the Source Expression column to specify where the approval form gets data for a particular target form field.

NOTE:When the Pre-Activity choice is selected, the cells in the Target Form Field column are not editable.

Post Activity

Allows you to specify one or more Post Activity mappings. When this option is selected, you can double-click a cell in the Target Expression column to specify where data from a form field should be copied after the form has been processed.

You cannot use Post Activity mapping with the Multiple and Quorum approver types (see Section 8.2.1, Properties).

The form for an Approval activity includes a special internal control called apwaComment. This control causes user comments to be written to the workflow database. It should not have a post-activity mapping. For more information on this control, see Section 6.5.9, DNMaker.

NOTE:When the Post-Activity option is selected, the cells in the Source Form Field column are not editable.

Source Expression

Specifies a source expression for a pre-activity mapping. When you click a cell in the Source Expression column, the ECMA expression builder displays to help you define your expression.

Target Expression

Specifies a target expression for a post-activity mapping. When you click a cell in the Target Expression column, the ECMA expression builder displays to help you define your expression.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions.

8.2.3 E-Mail Notification

To enable e-mail notification for the Approval activity, you need to specify the e-mail template to use, as well as source expressions for target tokens in the e-mail body.

Table 8-5 E-mail Notification Settings for the Approval Activity

Setting

Description

Notify

Specifies that this e-mail notification is a notification e-mail.

Reminder

Specifies that this e-mail notification is a reminder e-mail.

Retry Reminder

Specifies that this e-mail notification is a retry reminder e-mail.

Show System Tokens

Displays system tokens (for example, TO, CC, BCC, REPLYTO) in the Target column.

E-Mail Template

Specifies the name of the e-mail template to use. By default, the Approval activity uses the Provisioning Notification template.

You can edit an e-mail template in Designer. For more information, see Editing an e-mail template:.

Source/Target

Specifies the source expressions for target tokens in the e-mail body.

The list of target tokens is determined by the selected e-mail template. You cannot add new tokens, but you can assign values to the tokens by building your own source expressions. At runtime, source expressions are evaluated to determine the value of each token.

The available target tokens are listed below:

  • TO

  • CC

  • BCC

  • REPLYTO

  • recipientFullName

  • initiatorFullName

  • requestTitle

  • userFirstName

If you use a provisioning request definition template to create your workflow, each token has a default source expression. The default expressions retrieve values from the workflow process (the process object) or from the data abstraction layer (IDVault object). You can modify these expressions to suit your application requirements.

NOTE:When you create a workflow for use with the Resource Request portlet, and you use the “ _default_” as the expression for the TO token, the addressee expression must be an IDVault expression.

For details on building ECMA expressions, see Section 10.0, Working with ECMA Expressions.

NOTE:E-mail notification is only supported when the Notify participants by E-Mail check box is selected on the Overview tab, and the Notify by E-Mail property for the Approval activity is set to True.