Adding Virtual Approver PeopleCode

PeopleSoft designed Virtual Approver to simplify the PeopleCode that you must write for approval processes. Rather than writing complex PeopleCode programs, you define the approval rules using pages in the Workflow Administrator, then use two simple PeopleCode functions to check those rules.

After you add the Virtual Approver work pages to the component with the page where the triggering event occurs, you must add both SaveEdit PeopleCode and Workflow PeopleCode to the record definition that is associated with that page.

  • The SaveEdit PeopleCode uses the Virtual_Approver PeopleCode library function to check the approval rules that you defined in the Workflow Administrator and determine whether an item must be routed for approval.

  • The Workflow PeopleCode uses the Virtual_Router PeopleCode function to route items to the next step in the approval process.

Note:

The Virtual_Router PeopleCode library function is located in the FieldFormula event of the APPR_VA0_WRK.FUNCLIB_02 record field. The Virtual_Approver function is located on the FieldFormula event of the APPR_VA0_WRK.FUNCLIB_01 record field.

You must add the SaveEdit and Workflow PeopleCode to the same record field.

SaveEdit PeopleCode

This is the general structure of the SaveEdit PeopleCode program:

  1. Declare the external workflow functions Get_RoleUser and Virtual_Approver.

  2. Set values in the APPR_FIELDS_WRK work record to give the Virtual_Approver function the data it needs to check the approval rules.

    Set these values:

    • The name of the role user attempting to approve the transaction.

    • The business process and approval rule set that you want Virtual_Approver to use.

    • The approval action that the current user gave to the current work item. The valid status values are A (Approve), D (Deny), or R (Recycle).

  3. Use the Virtual_Approver function.

  4. Set the approval status record field to the value that Virtual_Approver returns: A (Approved), D (Denied), and P (Pending).

    Enter the following code exactly as it’s shown, replacing the values in angle brackets with the values that are appropriate for your application.

    /* Declare the Virtual Approver workflow functions */

    declare function Get_RoleUser PeopleCode APPR_VA0_WRK.ROLEUSER FieldChange;
declare function Virtual_Approver PeopleCode APPR_VA0_WRK.FUNCLIB_01 FieldFormula;

    /* Get the role user name for the current user */
    &USERID = %UserId;
Get_RoleUser(&USERID, &EMAILID, &FORMID, &EMPLID, &ROLEUSER);
    /* Set values in the work record for Virtual_Approver */
    APPR_FIELDS_WRK.ROLEUSER = &ROLEUSER;
APPR_FIELDS_WRK.BUSPROCNAME = BUSPROCESS.<BusProcessName>;
APPR_FIELDS_WRK.APPR_RULE_SET = <approval_rule_set>;
APPR_FIELDS_WRK.APPR_ACTION = <approval_action>;
APPR_FIELDS_WRK.APP_ROW_NUMBER = <current_row_number>;
    /* Call the Virtual Approver */
    Virtual_Approver();
    /* Set the application record’s approval status field to the value  */
/* Virtual_Approver returns */
    <status_record_field> = APPR_FIELDS_WRK.APPR_STATUS;

    The variables in this code are:

    Field or Control Description

    BusProcessName (business process name)

    The name of the business process whose approval rules you want to use.

    Approval_rule_set

    The name of the approval rule set that you want Virtual_Approver to use to determine whether an item needs further approval.

    Approval_action

    The approval action to provide Virtual_Approver as input. Usually, approval_action is the name of the record field in which the user sets the approval status. It can also be one of the string constants: P, D, or R.

    Note: If the user specifies the approval action at level 0 on the page, that is, if the user specifies a single approval action for the entire page, it’s preferable to include the field APPR_FIELDS_WRK.APPR_ACTION on the page and let the user set it directly. However, this direct approach doesn’t work if the user must specify approval actions for each row in a scroll. You must have the user set the action in another field, then transfer the value to the APPR_ACTION field before the Virtual_Approver call.

    Current_row_number

    The current row number in the scroll. Setting this field is not necessary at level 0.

    APPR_ROW_NUMBER is only required when Virtual Approver is triggered on a non-level-0 scroll.

    Status_record_field

    The record field that holds the approval status of the transaction, such as Purchase Request Approval Status.

The user should store the APPR_INSTANCE in the application table and pass it to the Virtual Approver. For example, APPR_FIELDS_WRK.APPR_INSTANCE = <application table>.APPR_INSTANCE. Optionally, the user can also pass the VA_BEHAVIOR_TYPE: APPR_FIELDS_WRK.VA_BEHAVIOR_TYPE = "1". Only the value of 1 is supported. The user can check the field value of APPR_FIELDS_WRK.VA_BEHAVIOR_STATUS after calling Virtual_Approver():

  • If the approval process has been denied, the value is 1.

  • If the approval process has been completed, the value is 2.

  • If the operation is at a lower step that has already been approved, the value is 3.

    If the user is on a step that has been approved by another user, the status of the "Resubmit VA Worklist" flag determines whether this is allowed.

    See Setting Workflow System Defaults.

Virtual Approver PeopleCode

The Virtual Approver PeopleCode looks like this:

declare function Virtual_Router PeopleCode APPR_VA0_WRK.FUNCLIB_02 FieldFormula;
APPR_FIELDS_WRK.APPR_VR_ROW = <scroll_info>;
Virtual_Router();
if None(APPR_INSTANCE) then
   <application record name>.APPR_INSTANCE = APPR_FIELDS_WRK.APPR_INSTANCE;
endif;

The scroll_info is a number. If you’re calling the router from level 0, scroll_info is 0; if you’re calling it from a scroll, scroll_info is the row number of the current row in the scroll. If you’re calling from a level 1 scroll, use the CurrentRowNumber PeopleCode function.

The if statement assigns an instance ID to a transaction if it does not already have one.