Sample Scenario 6: Requesting Multiple and Complex Approvals

These are the conditions in this scenario:

  • When a purchase order (PO) status is changed to Ordered, the PO requires the approval of the purchasing manager.
  • If the PO is for more than $100,000, the PO requires the approval of the purchasing manager’s supervisor.
  • If the PO is for more than $1,000,000, the PO requires the further approval of two senior executives.

If the PO is disapproved at any level, the PO is rolled back to the previous values, and any changes made are lost. During the approval process, the PO remains suspended until approval or disapproval is determined. If one or more approvers fail to respond to the request, the PO is locked and cannot be changed until all required approvers respond.

This flow diagram illustrates what must happen with this handler:

Sample Scenario 6

For this scenario:

  • Use the same global constant for the purchasing manager (PurchasingMgr) that you used in Sample Scenario 4: Approval for a New Record.
  • Use the IdoOnItemUpdate framework event for the SLPos IDO.

    This will cause the event to be generated whenever a PO record is updated in the Purchase Orders form or by other processes that perform the update through an IDO request.

  • Pass property values and an identifying property (ItemId) to the application event as input parameters so the system can store them with the application event as event parameters.

To accomplish this scenario:

  1. Create and save an event handler with these settings:
    Event Name
    Select IdoOnItemUpdate.
    Applies to Objects
    Specify SLPos.
  2. On the Event Global Constants form, create the required event global constants:
    Name Value Comments
    PurchasingMgr userID1

    The value is the logon user ID for the purchasing manager required for initial approval.

    The value can be the same as the one you created for Sample Scenario 4: Approval for a New Record.

    If you have multiple recipients, separate them with semi-colons and no spaces.
    PurchasingSuper userID2 The value is the logon user ID for the purchasing supervisor required to approve POs over $100,000.
    PurchasingSenior userID3;userID4 The values are the logon user IDs for the two senior executives required to approve POs over $1,000,000.
    SuperCost 100000

    This global constant represents the minimum amount that must be approved by a supervisor. You are using a global constant so that this value can be changed globally at some future time.

    The value is a literal amount. Do not add commas.
    SeniorCost 1000000

    This global constant represents the minimum amount that must be approved by a supervisor. You are using a global constant so that this value can be changed globally at some future time.

    The value is a literal amount. Do not add commas.
    POApprovalPrompt See below. Because you want to use the same basic prompt for all levels of approvals, you must place this value into a global constant. This is accomplished with the use of a few variables.
    Value for POApprovalPrompt:
    SUBJECT(" Purchase Order Update Approval Needed")
CATEGORY("Order Approval")
TO(GC(TV(Approver)))
BODY(SUBSTITUTE("A purchase order, {0}, has been updated to Ordered status for vendor,
{1}, number: {2}. Please review the details on the Variables tab and then indicate your approval on the Response tab.",
FP("PoNum"),
P("VendorName"),
FP("VendNum")))
QUESTION("Do you approve this PO change?")
CHOICES("1, sYes, 0, sNo")TV(CountMethod)
FILTERFORM("PurchaseOrders")
FILTER( SUBSTITUTE("PoNum={0}", FP("PoNum")))
  3. Add the first event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 1.
      Action Type
      Select Finish.
    2. Starting with the Edit Parameters button, use the event action parameter forms to complete the event action:
      Field or Button Action Result or Comments
      Condition Click this button. The Event Action Parameter Condition form is displayed.
      Expression 1 Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select PROPERTYMODIFIED. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify Stat.
      2. Click OK.
      		 The system returns the expression to the Event Action Parameter Condition form.
      NOT Select this check box.
      Condition Specify OR P("Stat") <> "O".
      Note: The reason this is required is that the Event Action Parameter Condition form can only be used to construct simple condition statements. For complex conditions, you can start with that form, but you must then manually edit the condition statement.

      The "O" in this case is the capital letter, not a zero.

      The final result of this condition is:

      • If the Stat property is not modified, or if the value of the Stat field is not O, then finish.
      • If the Stat property is modified and the value of the field is O, then continue to the next action.
      OK Click this button. The system returns the expression to the Event Action Finish form.
    3. To verify that there are no syntax errors, click Check Syntax.
    4. Save the action.
  4. Add the second event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 2.
      Action Type
      Select Set Values.
    2. Starting with the Edit Parameters button, use the event action parameter forms to complete the event action:
      Field or Button Action Result or Comments
      Variables Click this button. The Event Action Set Name/Value Pairs form is displayed.
      Variable Name row 1 Specify Approver.
      Value row 1 Specify PurchasingMgr.
      Variable Name row 2 Specify CountMethod.
      Value row 2 Specify VOTINGRULE(Plurality). Although this value is similar to a function, the system in this case does not treat VOTINGRULE() as other functions.
      OK Click this button. The system returns to the Event Action Set Values form.
      OK Click this button. The system returns the parameters to the Event Actions form.

      This action step sets the values of these variables:

      • The variable named Approver is set to the value of the global constant, PurchasingMgr, which is the user ID for the purchasing manager.
      • The variable named CountMethod is set to count the votes using the Plurality rule, which simply says that the choice with the greatest number of votes wins. Since you have only one individual set to vote at this point, the purchasing manager’s vote alone determines what happens next.
    3. To verify that there are no syntax errors, click Check Syntax.
    4. Save the action.
  5. Add the third event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 3.
      Action Type
      Select Prompt.
      Parameters
      Specify TGC(POApprovalPrompt).
      Note: Because TGC( ) is a pre-parser function, you cannot use the event action parameter forms to create or set this statement. You must specify this statement directly in the Parameters field of the Event Actions form. This also means that you cannot use the Check Syntax button to check the syntax.

      This statement performs a text evaluation of the POApprovalPrompt global constant to obtain the parameters for a prompt action. Part of this text evaluation includes an evaluation and insertion of the values for the two variables you set in the previous step.

      After evaluating the POApprovalPrompt global constant, this action also sends out the prompt message to the purchasing manager and suspends the handler pending the manager’s response. Because you did not specify any Variable Access rules, the message allows the purchasing manager to modify any variable values before approval.

    2. Save the action.
  6. Add the fourth event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 4.
      Action Type
      Select Branch.
    2. Starting with the Edit Parameters button, use the event action parameter forms to complete the event action:
      Field or Button Action Result or Comments
      Condition Click this button. The Event Action Parameter Condition form is displayed.
      Expression 1 Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select VOTINGRESULT. The system displays the Action drop-down list.
      Action Select 3 Prompt. The Action field displays 3.
      OK Click this button. The system returns to the Event Action Parameter Condition form.
      Operator Select <>.
      Expression 2 Specify 1.
      OK Click this button. The system returns to the Event Action Branch form.
      Destination Specify 14. Even though the action Sequence 14 is not yet created, you can specify the number here. This action eventually jumps if the purchasing manager rejects the request.
      OK Click this button. The system returns the actions to the Event Actions form, correctly formatted.

      This action step evaluates the purchasing manager’s response (from action Sequence 3) and directs the handler to the next action depending on that response. If the manager approves the request, the handler continues to the next action. If the manager rejects the request, the system goes to the destination, action Sequence 14, and continues from there.

    3. To verify that there are no syntax errors, click Check Syntax.
    4. Save the action.
  7. Add the next event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 5.
      Action Type
      Select Finish.
    2. Starting with the Edit Parameters button, use the event action parameter forms to complete the event action:
      Field or Button Action Result or Comments
      Condition Click this button. The Event Action Parameter Condition form is displayed.
      Expression 1 Click this button. The Event Action Expression Editor form is displayed.
      Select a function Select P. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify POCost.
      2. Click OK.
      		 This property name is derived from the Purchase Orders form.

      The system returns the expression to the Event Action Parameter Condition form.
      Operator Select <.
      Expression 2 Specify 1. The Event Action Expression Editor form is displayed.
      Select a function Select GC. The system displays the Argument 1 button and field.
      Argument 1
      1. Specify SuperCost.
      2. Click OK.
      		 The system returns the statement to the Event Action Parameter Condition form.
      OK Click this button. The system returns the condition parameter to the Event Action Finish form.
      Result Specify Approved by Purchasing Manager.
      OK Click this button. The system returns to the Event Actions form with the parameters correctly formatted.

      This action step determines whether the cost of the PO is less than $100,000, the value of the SuperCost global constant. If it is, then the handler commits the PO record to the database, writes the result to the event state (viewable on the Event States form), and finishes with a status of Success. If the PO cost is $100,000 or greater, then the handler continues to the next action.

  8. Add the next event action:
    Action Sequence
    Specify 6.
    Action Type
    Select Set Values.

    This action step is similar to action Sequence 2, with these differences:

    • The variable named Approver is set to the name of the global constant, PurchasingSuper, which contains the user ID for the purchasing manager’s supervisor.
    • The variable named CountMethod is set to count the votes using the Majority rule, which says that any choice that gets more than 50% of the vote wins. If you have three supervisors voting, for instance, whichever choice gets the first two votes determines the outcome. Since you have only one individual set to vote at this point, the purchasing supervisor’s vote alone determines what happens next.
  9. Add the next event action:
    Action Sequence
    Specify 7.
    Action Type
    Select Prompt.
    Parameters
    Specify TGC(POApprovalPrompt).

    As in action Sequence 3, this action step performs a text evaluation of the POApprovalPrompt global constant to obtain the parameters for a prompt action. This time, the prompt uses the new variable values for the purchasing supervisor that are set in Step 8.

    After evaluating the POApprovalPrompt global constant, this action sends out the prompt message to the purchasing supervisor and suspends the handler again, pending the supervisor’s response. Again, because you did not specify any Variable Access rules, the message allows the purchasing supervisor to modify any variable values before approval.

  10. Add the next event action:
    Action Sequence
    Specify 8.
    Action Type
    Select Branch.

    This action is similar to action Sequence 4, with the sole difference being that for the VOTINGRESULT( ) expression, you look at action Sequence 7 instead of Sequence 3.

    This action, then, evaluates the purchasing supervisor’s response (from Action Sequence 7). As soon as any choice has a majority (more than 50% of the votes), the system directs the handler to the next action depending on that response.

    In this case, if the supervisor approves the request, the handler continues to the next action. If the supervisor rejects the request, the system goes to the destination, action Sequence 14, and continues from there.

  11. Add the next event action:
    Action Sequence
    Specify 9.
    Action Type
    Select Finish.

    This action is similar to action Sequence 5, with these differences:

    • The global constant to use for the condition expression is SeniorCost, instead of SuperCost.
    • The Result statement should read: Approved by both the purchasing manager and the purchasing supervisor.

    This action step determines whether the cost of the PO is less than $1,000,000, the value of the SeniorCost global constant. If it is, then the handler commits the PO record to the database, writes the result to the event state (viewable on the Event States form), and finishes with a status of Success. If the PO cost is $1,000,000 or greater, then the handler continues to the next action.

  12. Add the next event action:
    Action Sequence
    Specify 10.
    Action Type
    Select Set Values.
    SETVARVALUES(Approver="PurchasingSenior",
CountMethod="VOTINGRULE(MinimumPercentage) MINIMUM(100)")

    This action step is similar to action Sequences 2 and 6, with these differences:

    • The variable Approver is set to the name of the global constant, PurchasingSenior, which contains the user IDs for the senior-level executives who must approve requests over $1,000,000.
    • The variable named CountMethod is set to count the votes using the MinimumPercentage rule, which says that the first choice to reach a minimum percentage determines the next action. In this case, the minimum percentage is 100%, so all recipients must approve for the PO to reach final approval. If any recipient rejects the request, the entire request is rejected, no matter who has approved it to that point.
      Note: The MinimumPercentage voting rule requires that you specify a minimum percentage for passage. This means that, in addition to the VOTINGRULE( ) keyword, you must also specify the MINIMUM( ) keyword as part of the variable definition. The resulting declaration for the Value column of the CountMethod variable is: VOTINGRULE(MinimumPercentage) MINIMUM(100).
  13. Add the next event action:
    Action Sequence
    Specify 11.
    Action Type
    Select Prompt.
    Parameters
    Specify TGC(POApprovalPrompt).

    As in action Sequences 3 and 7, this action step performs a text evaluation of the POApprovalPrompt global constant to obtain the parameters for a prompt action. This time, the prompt uses the new variable values for the senior-level executives that are set in the previous step.

    After evaluating the POApprovalPrompt global constant, this action sends out the prompt message to the senior executives. Again, because you did not specify any Variable Access rules, the message allows the executives to modify any variable values before approval.

  14. Add the next event action:
    Action Sequence
    Specify 12.
    Action Type
    Select Branch.

    This action is similar to action Sequences 4 and 8, with the difference that for the VOTINGRESULT( ) expression, you look at action Sequence 11.

    This action step evaluates the senior executives’ responses (from action Sequence 11). If both executives vote to approve the request, then the handler moves on to the next action. If either or both of them vote to reject the request, then the handler goes to the destination, action Sequence 14, and continues from there.

  15. Add the next event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 13.
      Action Type
      Select Finish.
    2. Click Edit Parameters.
    3. In the Event Action Finish > Result field, specify Purchase order change approved by senior purchasing executives.
      This action sequence commits the PO record to the database, writes the result to the event state (viewable on the Event States form), and finishes with a status of Success.
    4. Save all actions.
  16. Add the next event action:
    1. On the Event Actions form, specify this information:
      Action Sequence

      Specify 14.

      Action Type

      Select Notify.

      For any result which ends up in a disapproval of the request change, this action step sends a notification message to the individual who made the original change to the PO status, letting that individual know that the change request has been disapproved at some level.

    2. Use the event action parameter forms to create this notification message event action: 
      TO(ORIGINATOR())
SUBJECT(SUBSTITUTE("Purchase order {0} change request disapproved",
FP("PoNum"))
CATEGORY("Notification")
BODY(SUBSTITUTE("Your purchase order change request for PO {0} for {1}, vendor number:
{2} has been disapproved. If you have questions, please see the required approvers.", 
FP("PoNum"),
P("VendorName") ,
FP("VendNum"))) 
SAVEMESSAGE(FALSE)
    3. To verify that there are no syntax errors, click Check Syntax.
    4. Save the action.
  17. Add the final event action:
    1. On the Event Actions form, specify this information:
      Action Sequence
      Specify 15.
      Action Type
      Select Fail.
    2. In the Event Action Fail > Result field, specify PO change not approved.
      This action step writes the result of the rejection to the event state (viewable on the Event States form), and exits with a status of Failure.
  18. Now that all event actions (including the requisite adjourning actions) have been created and saved, go back to the Event Handlers form and select the Suspend check box.
  19. Save the handler.
  20. Optionally, click the Diagram button to view the diagrammatic view of the event handler flow in the Event Handler Diagram form.
  21. Discard the cached metadata.
  22. Test the event handler.

In this scenario, keep these points in mind:

  • Whenever possible, use the event action parameter forms thorough the Edit Parameters button. This is your best insurance against syntax errors.
  • Not all actions can be created using the event action parameter forms. This is particularly true of the pre-parser functions. In these cases, you cannot check the syntax for these actions using the Check Syntax button.
  • You can create whole actions using global constants. Although, you cannot subsequently check these for syntax errors by using the Check Syntax button, so proceed with caution.

Extra challenges are:

  • Adding the user ID to the Result statements for both approvals and disapprovals.
  • Having the system generate a message to the user who initiated the request notifying the user that the request has been approved.
Related topics