The Approval activity is a user-facing activity that displays an approval form that allows users to 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 III, Working with Forms Catalog.
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.
The Approval activity includes the following properties:
Table 10-5 Approval Activity Properties
|
Property Name |
Description |
|---|---|
|
Identifier |
A unique string value that identifies the activity. Workflow Builder generates this value automatically in the <Activity>_<N> format, where <Activity> represents the name of the activity and <N> represents an alphanumeric value that contains seven characters. |
|
Name |
Provides a name for the activity. |
|
Form |
Specifies the name of the approval form to display at runtime. Select the name of the form you want to use, or create a new form. For information on how to create new form using Form Builder, see Creating New Forms. After you select the form, map the data items to include in the form from the listed data items. You must associate a form with a Approval activity. If you do not specify a form an error message appears at runtime. |
|
Approver Type |
Specifies the number of addresses that are allowed and the approval pattern that is enforced for this activity. The choices are:
For information about how the Approver Type property interacts with the Addressee property, see Specifying the Addressee Property. |
|
Addressee |
Specifies a dynamic expression that identifies the addressee for the activity. The addressee is the approver of the workflow. The addressee is determined at runtime, based on the evaluation of the expression. The Workflow Administration Console validates that the expression is a valid ECMA expression. It cannot validate whether the expression resolves to a valid object (such as a role) or whether that object will exist at runtime. For information on specifying addressees, see Specifying the Addressee Property. For more information about developing valid addressee expressions, and about how the Addressee property interacts with the Approver Type property, see Specifying the Addressee Property. HINT:To simplify the process of testing a new workflow, you can set the addressee to be the recipient. Doing so removes the need to log out of the application and log in again as a manager each time you want to test your forms. This technique is 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 Using the ECMA Expression Builder. For descriptions of the system variables available in a workflow, see Understanding Workflow Data. |
|
Reminder Start |
Specifies a dynamic expression that defines, in milliseconds, the time to send the first reminder email. 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 Objects pane of the ECMA expression builder. This property is part of the reminder email function. If this activity is considered important and needs to be acted on quickly, you can configure the activity to send a reminder email to the activity addressee. For example, you can configure the reminder settings to send a reminder email five days before the activity times out, and on a daily basis until the activity times out. To do so, specify a Reminder Start time, a Reminder Interval, and the email to be sent (see Email Template). For details on building ECMA expressions, see Using the ECMA Expression Builder. For descriptions of the system variables available in a workflow, see Understanding Workflow Data. |
|
Reminder Interval |
Specifies a dynamic expression that defines the interval between sending reminder emails. You can select predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Objects 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 Using the ECMA Expression Builder. For descriptions of the system variables available in a workflow, see 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 to give this user an opportunity to finish the work of the activity. If the last attempt times out, the activity can be marked as approved, denied, refused, timed out, or in error, depending on the final timeout action specified for the activity. |
|
Escalation Interval |
Not available when the 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 addressee executes 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 also specify an Escalation Count of 3 minutes 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. When the activity completes, the workflow engine follows the link defined by the final timeout action. For details on building ECMA expressions, see Section 11.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see 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 email (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 Objects 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 select predefined expressions that represent common intervals (for example, hour, day, week) in the ECMAScript Objects pane of the ECMA expression builder. |
|
Final Timeout Action |
Determines the final state of the request if the workflow times out. The choices are:
|
|
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 addressee executes the activity. 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 minutes 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. When the activity completes, the workflow engine follows the link defined by the final timeout action. For details on building ECMA expressions, see Section 11.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Understanding Workflow Data. |
|
Timeout Units |
Determines the unit of measure used for the timeout interval. The choices are:
|
|
Exclude Requester |
Specifies whether requestors can approve their own provisioning requests.
|
|
Notify by E-Mail |
Specifies whether this activity should send email notifications. Set to “True” to notify by email; otherwise, set to False. Specifies the email to send using the Email Template tab (see Email Template). To use this feature, the Notify participants by Email parameter for the provisioning request definition must be set to “True”. |
|
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"). |
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, Entity.get('/api/entity', 'group', {groupIdHere}, ['members']).
To bind the data items associated with the Approval activity, 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 through expression calls to the directory abstraction layer. The post-activity mappings move form data back into the flowdata object.
Table 10-6 Approval Activity Data Item Mappings
|
Setting |
Description |
|---|---|
|
Pre Activity |
Allows you to specify one or more pre-activity mappings. When you select this option, you can click a cell in the Source Expression column to specify where the approval form gets data for a particular target form field. The pre-activity mapping expression is evaluated twice before the form is presented, once during the initial presentation of the form and again before the post activity, to ensure that all the values on the form have a valid type including those that were not initialized. As a result, any calls made to external systems are made twice. For example, a call that retrieves a unique counter for a value makes two calls that allocates two counters, with the last one requested being used. NOTE:
|
|
Post Activity |
Allows you to specify one or more post-activity mappings. When you select this option, you can 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 mappings with the Multiple and Quorum approver types, see 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. NOTE:When you select the Post Activity option, you cannot edit the cells in the Source Form Field column. |
|
MAP ALL |
Allows you to generate data from the Pre Activity column, that is stored in a variable, to the Post Activity column. |
|
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 appears 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 appears to help you define your expression. |
For details on building ECMA expressions, see Section 11.0, Working with ECMA Expressions.
The Approval activity provides several default methods to use in ECMAScript expressions. Some methods are displayed in the ECMAScript Objects pane of the ECMA expression builder, while others must be entered manually into the text area provided in the ECMA expression builder.
Table 10-7 Available ECMAScript Methods for Approval Activities
|
Object |
Method |
Description |
|---|---|---|
|
Action |
Activity-ID.getAction() |
Returns the approval action taken by the activity. Possible options are:
|
|
Addressee |
Activity-ID.getAddressee() |
Returns the DN of the user who needs to approve or deny the requested action. |
|
Name |
Activity-ID.getName(locale) |
Returns the name of the approval activity for the specified locale. |
|
Timestamp |
Activity-ID.getTimestamp() |
Returns the date and time of any approval action taken by the user or system, including approved, denied, refused, timed out, or error. |
|
User |
Activity-ID.getUser() |
Returns the approver’s DN of the work task for the activity. |
|
WorkId |
Activity-ID.getWorkId() |
Returns the work item ID for the activity. |
|
Addressee List |
Activity-ID.getAddresseeList() |
Returns a list of DNs of all users who need to approve or deny the requested action. |
|
Notify Addressee |
Activity-ID.getNotifyAddressee() |
Returns the full name of the user who needs to approve or deny the requested action. |
To enable email notification for the Approval activity, you must specify the email template to use, as well as source expressions for target tokens in the email body.
Table 10-8 E-mail Notification Settings for the Approval Activity
|
Setting |
Description |
|---|---|
|
Notify |
Specifies that this email notification is a notification email. |
|
Reminder |
Specifies that this email notification is a reminder email. |
|
Escalation Reminder |
Specifies that this email notification is a retry reminder email. |
|
Show Default Tokens |
Displays default tokens (for example, TO, CC, BCC, REPLYTO, TO_DN, CC_DN, and BCC_DN) in the Target column. |
|
E-Mail Template |
Specifies the name of the email template to use. By default, the Approval activity uses the “Provisioning Notification template”. You can edit an email template in the console. For more information, see Editing an email template:. |
|
Source/Target |
Specifies the source expressions for target tokens in the email body. The list of target tokens is determined by the selected email template. You cannot add new tokens, but you can assign values to the tokens by building your own source expressions. At runtime, the source expressions are evaluated to determine the value of each token. The available target tokens are listed below:
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). You can modify these expressions to suit your application requirements. For details on building ECMA expressions, see Section 11.0, Working with ECMA Expressions. |
NOTE:
Email notification is supported only 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”.
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 ECMA expression.
If you create an activity using any of the target tokens TO_DN, CC_DN, or BCC_DN, you must specify a user’s DN or an expression that resolves to a user’s DN as the source expression for the token.
If you create an activity using both the target tokens TO and TO_DN, the workflow sends duplicate notification emails to the target users.
To address an Approval activity, you must enter a valid expression for the Addressee property. The addressee is the approver for the activity. The number of approvals that are required to approve the activity is determined by the relationship between the Addressee property and the Approver Type property, as described in Relationship Between Addressee and Approver Type.
To build the addressee expression:
Click the plus sign (+) next to Addressee. (Available only for Group, Multiple or Quorum )
Enter a value in the Addressee field, then click OK.
NOTE:For each addressee, you must add a separate entry, then enter the name separately.
(Optional) To add a new addressee by using the expression builder, click the icon next to the Addressee field.
(Optional) Choose one of the ECMAScript Objects to build the addressee expression. For example, if you do not know the name of the addressee, but you know the user ID, you can use User ID from Source to build the expression, Entity.get('/api/entity', 'user', { userIdHere }, ['userId']). Then replace 'userIdHere’ with the user ID of the addressee. At runtime, the user ID is evaluated and the task is sent to the appropriate approver.
(Optional) Click OK.
NOTE:When the approver type is “Quorum”, you must specify the Quorum Type. At runtime, the Quorum Expression is evaluated and replaced with a meaningful value, whereas for Quorum Constant the value is displayed exactly as entered in the field.
An Addressee expression must resolve to one of the following at runtime:
A valid individual addressee that can be a user DN, a group DN, or a role DN.
A valid list of addressees (for example, created using a Java vector object) that can contain multiple user DNs, multiple group DNs, or multiple role DNs, or a mixture of both.
Because the addressee is the approver, the maximum number of approvals possible equals the number of addressees (the number of user DNs plus the number of group DNs or role DNs) and does not include or count the individual members of a group or roles.
NOTE:A Group DN or a Role DN is always processed to contribute a single vote (that is, when one member of a group or role claims an activity, the rest of the members of the group or role can no longer see or claim the activity), regardless of the approver type.
The following table provides examples of valid addressee expressions that you can create using the ECMA expression builder.
Table 10-9 Examples of Addressee Expressions
|
Type of Expression |
Example |
|---|---|
|
Individual user DN |
'uniqueUserIdHere' |
|
Individual group DN |
'uniqueGroupIdHere' |
|
Individual role DN |
'uniqueRoleIdHere' |
NOTE:Roles are specific to products.
Because the addressee is the approver, the behavior of the workflow and the total number of affirmative approvals needed varies, depending on the type of addressee that is specified by the Addressee expression, and the Approver Type that is selected.
The following table describes the workflow behavior when different types of addressee are used with the Normal approver type.
Table 10-10 Workflow Behavior with the Normal Approver Type
|
Addressee Value |
Description |
|---|---|
|
Individual User DN |
|
|
Individual Group DN |
|
|
Individual Role DN |
|
|
Multiple User DNs |
Not allowed. |
|
Multiple Group DNs |
Not allowed. |
|
Multiple Role DNs |
Not allowed. |
|
Mixture of Users, Groups, and Roles |
Not allowed. |
If a workflow is assigned to a group, and email notification is used for the approvals, all members of the group are sent an email. If a proxy user is assigned to any members of the group, the processing works as follows:
If the approver is a single user, then the email notification is sent to both users (the original and proxy users).
If the approver is a group DN, and one of the users in the group is assigned a proxy user, the proxy user is not notified by email when a new request is placed in the task list.
If you want the proxy user to be notified by email, assign the approval task to the members of the group, and select Group Approver as the approver type. For example, if you assign the approval activity to:
Entity.get(('/api/entity', 'group', {groupidhere}, ['members']),groupIdHere must be replaced with a unique group ID.
When you set the approval type to “Group”, a notification is sent to each member's proxy (if the member has a proxy). One member of the group can claim and act on the approval task as if you assigned it directly to the group DN.
The following table describes the workflow behavior when different types of addressee are used with the Group approver type.
Table 10-11 Workflow Behavior with the Group Approver Type
|
Addressee Value |
Description |
|---|---|
|
Individual User DN |
|
|
Individual Group DN |
|
|
Individual Role DN |
|
|
Multiple User DNs |
|
|
Multiple Group DNs |
|
|
Multiple Role DNs |
|
|
Mixture of Users, Groups, and Roles |
|
The following table describes the workflow behavior when different types of addressees are used with the Multiple approver type.
Table 10-12 Workflow Behavior with the Multiple Approver Type
|
Addressee Value |
Description |
|---|---|
|
Individual User DN |
|
|
Individual Group DN |
|
|
Individual Role DN |
|
|
Multiple User DNs |
|
|
Multiple Group DNs |
|
|
Multiple Role DNs |
|
|
Mixture of Users, Groups, and Roles |
|
The following table describes the workflow behavior when different types of addressee are used with the Quorum approver type.
Table 10-13 Workflow Behavior with the Quorum Approver Type
|
Addressee Value |
Description |
|---|---|
|
Individual User DN |
|
|
Individual Group DN |
|
|
Individual Role DN |
|
|
Multiple User DNs |
|
|
Multiple Group DNs |
|
|
Multiple Role DNs |
|
|
Mixture of Users, Groups, and Roles |
|
If the expression specified in the Addressee property of an Approval activity evaluates to a non-existent DN (for example, if the expression was hard-coded incorrectly, calculated incorrectly, or submitted incorrectly by a user selection), no indication is given that the workflow is not processing normally. The Application Server Console displays a normal forward message, and the Comment and Flow history shows a normal “assigned” message. To avoid this issue, we recommend the following best practices:
Use a Condition activity before the Approval activity, and validate the addressee in the Condition activity.
For the Approval activity, specify a timeout interval and a link that performs the desired action in case the workflow times out.
The Problems tab provides details of the errors and warnings associated with the activity in a workflow. For more information about validating workflow activities, see Validating a Workflow.