Defining Parameterized Get Next Approver rules

The Parameterized Get Next Approver rule enables requesters and approvers working with a Parent-Child, Level, or Rule-Based process to add an approver anywhere in the approval hierarchy at run time. This rule type works with the preview feature to make this functionality available. See Adding-previews-to-your-approval-application.

For example, an approver using the preview feature in a Parent-Child process might see the following hierarchy of approvers:

1. Allan
2. Lin
3. Akon
4. Penni A Parameterized Get Next Approver rule would allow approver Lin to enter an additional approver, Michel, at the same level as Penni, for example. 
   You use the Parameterized Get Next Approver rule in combination with the Add-PGNA-Values application command. The Add-PGNA-Values command populates the detail record with the run-time variables to be used by the rule. See Process-commands.
   A Parameterized Get Next Approver rule works exactly like a Get Next Approver rule, with the following exceptions:
   • You can use run-time variables in the qualification and Set Fields operations.
   • Approvers can be added to any level, not only the next level.
   • After the Get Next Approver rules are run, the server runs all Parameterized Get Next Approver rules. If Parameterized Get Next Approver rules exist, but the current record does not supply any parameters, the Approval Server the Approval Server skips the parameterized rules.

To define a Parameterized Get Next Approver rule

1. Follow the procedure in Creating-a-rule to complete the basic information about the rule.
   • Select Parameterized Get Next Approver from the Rule Type list.
   • The Run If condition is optional. Use this field to define a conditional statement to control whether the rule runs.
2. In the If Multiple Results field, select a value from the menu.
    This field determines what occurs when more than one row of data is returned by the Get Next Approver rule. The following choices are available:
   • Value from First—Uses the value from the first record retrieved.
   • Values from All—Uses all of the values retrieved.
   • Return Error—Returns an error message if more than one record is retrieved.
   • Clear—Leaves this field blank.
3. In the If Multiple Approvers field, select a value from the menu.
    This field value determines the signature requirements when more than one approver is returned by the Get Next Approver rule.
   • One Must Sign—A single signature record is created and only one of the approvers listed in the record is required to act upon the approval request to consider the record complete.
   • All Must Sign—A separate signature record is created for each individual in the approver list, including individuals within a role. In this case, all of the approvers retrieved by the Get Next Approver rule must act upon the approval request.
   • Clear—Leaves this field blank.
4. In the Next Approver Rule Is field, select a value from the menu.
    This field value determines how the approver list is constructed when multiple Get Next Approver rules are included in the process.
   • Additive—Indicates that any name or role this rule assigns to the approver list is added to the existing approver list, and further rules are to be processed.
   • Ending—Indicates that any name or role this rule assigns to the approver list is added to the existing approver list, but no further rules are to be processed.
   • Exclusive—Indicates that this rule assigns the entire approver list, and no further rules are processed. In addition, if a previous rule created an approver list, that list is ignored.
   • Clear—Leaves this field blank.
5. Select Yes or No from the Guaranteed Add list.
   • Yes—The parameterized rule runs even when a Completion rule would otherwise determine that the process is done, thus guaranteeing that the user will be added as an approver.
   • No—If a Completion rule determines that the conditions exist for the process to be done, the process does not return to the Get Next Approver stage to run this rule.
6. Click the Set Fields tab.
7. In the Set Fields Type field, select the appropriate action type. See Defining-actions-for-a-rule.
8. For a query, select a form name from the From Form menu. This value indicates in which form to search for the query.
9. In the On Server field, select the server where the form is located.
   • Current—The form exists on the current server.
   • Alternate—The form exists on another server. In this case, type the server name where the form is located in the Server field.
10. Depending on the action type, enter the qualification statement or command line in the Qualification area.
11. In the Fields Data area, enter the name of the field or fields to receive the data in the Field Name column, and a value statement or the name of each source form field in the Value column.
12. Click Save.

Example of Parameterized Get Next Approver rule

The following figure illustrates an how an example Parameterized Get Next Approver rule operates. The example rule includes the following settings:

• Run If qualification: $Level$ = "%1"
• Guaranteed Add: Yes
• Set Fields: $Next Approver$ = "%2"

Example of a Parameterized Get Next Approver rule

The following actions occur:

1. A user enters an approval request in a process that includes an approval hierarchy, such as a Parent-Child or Level process.
2. When working with the approval request, the first approver uses the preview feature to view the existing approvers for the request, for example, by clicking a button on the approval form. The approver decides to add Michel LeTourneau as an approver at a future level, for example, level 4.

3. The approver uses functionality added to the approval request form, such as a button that opens an "Add Approvers" form, to enter the level and the approver name. When the approver saves his or her changes, a filter runs that captures these values and sends an Add-PGNA-Values application command using the values to the Approval Server, for example:

   *Application-Command Approval Add-PGNA-Values -o "My Param Rule" -l "4/Michel LeTourneau"*
4. The Approval Server receives the command, and stores the data in the Param Data field on the AP:Detail record.
5. After the Approval Server runs the Get Next Approver rules, it runs Parameterized Get Next Approver rules. While running the parameterized rules, it retrieves the values from the Param Data field in the detail record. In this case, it retrieves 4/Michel LeTourneau and parses this into %1="4" and %2="Michel LeTourneau"
6. The Approval Server replaces the variables in the Parameterized rule with these values:
   • Run If qualification—$Level$ = 4
   • Set Fields—$Next Approver$ = "Michel LeTourneau"
7. If the condition matches, the Set Fields action is executed. If the condition never matches and the regular Get Next Approver rules do not return any approvers, the Approval Server checks for the Guaranteed Add flag. If this is set to yes, the parameterized rule executes, even though the Run If condition is not satisfied.

Parameterized Get Next Approver rules are executed when a preview is generated, so the added approver is visible when future approvers preview the request.