Defining Approval Processes

This chapter provides overviews of approval processes, Virtual Approver, and approval rule sets and discusses how to:

• Create approval rule sets.

• Define approval rules.

• Maintain approval rules.

• Trigger Virtual Approver routings.

• Review approval history.

• Use GetApprovers PeopleCode.

Understanding Approval Processes

Approval processes are a common form of business process. The approval steps that you place on the approval rule set map represent the approval levels that are required for the activity.

A typical approval process incorporates many business rules, for example:

• Employees can approve purchases up to a given amount, based on their level in the organization: supervisors can approve up to 500 USD, managers up to 5000 USD, and so on.

• All product improvement requests are approved by both a manufacturing representative and a safety inspector.

• People can approve items for their own departments only.

• If an item requires a vice president’s approval, bypass the usual step of manager approval.

Business rules like these are usually incorporated into Workflow PeopleCode programs. Logical statements in the PeopleCode check the data on the page, such as the page where employees enter purchase requests, to determine whether the conditions are right for entering a work item into the workflow.

With approval rule sets, you define approval rules on a graphical map.

Features That Are Common to Virtual Approver and GetApprovers

Virtual Approver and GetApprovers PeopleCode share the following advantages:

• You can determine the appropriate approver for each approval step.

• You define and configure approval rules using the same PeopleSoft Application Designer interface that you use to develop all business process maps.

• You can define different approval rules for different business processes and multiple sets of rules for the same process.

• You can build multistep approval processes, with steps occurring sequentially or in parallel.

• You access the approval rule set through built-in PeopleCode functions.

  Virtual Approver uses the functions Virtual_Approver and Virtual_Router. GetApprovers is a PeopleCode function. In both cases, the functions use the approval rule set to determine whether approvals are needed and who the appropriate approvers are. To change a rule, you change the approval rule set rather than the PeopleCode.

• Users enter transactions by entering data onto a PeopleSoft application page.

  When they save a page, Virtual Approver or GetApprovers checks the approval rules that you’ve defined to determine the necessary approvals.

Differences Between Virtual Approver and GetApprovers

Virtual Approver and GetApprovers PeopleCode differ in significant ways. Use the information in the following table to decide which is appropriate in a given situation:

Note. Because GetApprovers returns only a list of approvers, it can be used with Virtual Approver without disrupting normal Virtual Approver functionality. You might use GetApprovers and Virtual Approver together to add forecasting capability to Virtual Approver.

Understanding Virtual Approver

This section discusses:

• Virtual Approver.

• Virtual Approver templates.

• User list roles for organizational levels.

Virtual Approver

Approval rule sets are PeopleSoft Application Designer definitions that are similar in appearance to workflow maps. Approval rule sets reference business processes, but they are not embedded within business processes (unlike activities, which are part of business processes). That is, approval rule sets are not represented by physical icons on workflow maps.

Instead, approval rule sets are separate definitions that are referenced by Workflow PeopleCode. Specifically, Virtual Approver finds the next approver by calling Virtual_Approver() and then sends that person a workflow notification by calling VirtualRouter(). You use different PeopleCode to trigger Virtual Approver than you use for other workflow events, but the function of the PeopleCode is the same: to identify the next users and to send them notifications.

To examine how Virtual Approver fits into PeopleSoft Workflow, consider a business process for ordering supplies. The first two activities within this business process are for creating orders and approving orders.

The Create Order activity consists of a single step: entering the order information into the PeopleSoft system.

When an employee enters an order, PeopleCode triggers Virtual Approver, which reads the specified approval rule set to determine whether the order requires approval and, if so, who must approve the order. When an order requires approval, Virtual Approver sends a routing to the approver. The approver works on the item using the activity that is specified in the first step of the approval rule set—in this case, the Approve Order activity.

The Approve Order activity also consists of a single step: approving the requisition. The approver can approver the order, deny the order, or recycle the order back to the original requestor for changes.

This diagram illustrates an Approve Order activity:

When the approver is finished, PeopleCode again triggers Virtual Approver. Virtual Approver PeopleCode includes a parameter that specifies the approval action. Valid actions are A (Approve), D (Deny), or R (Recycle).

If the approver approves the action, Virtual Approver checks the approval rule set to determine whether additional approvals are required.

• If additional approvals are not needed, Virtual Approver triggers the Authorized Order event, which sends a confirmation email message to the original user and sends a worklist routing to the buyer who places the purchase order.

• If additional approvals are needed, Virtual Approver triggers the Approve Order event again.

  This is the same event that was triggered when the original user first submitted the order, but when Virtual Approver determines who must approve the order, the routing goes to the next person in the approval chain.

If the approver denies the order, Virtual Approver triggers the Deny Order event, which sends an email message notifying the original user that the order was denied.

If the approver recycles the order, Virtual Approver triggers the Recycle Order event, which sends an email message telling the person who is defined in the routing (either the original submitter or the previous approver) to change the order and resubmit it.

As you can see, the workflow maps show the events and routings that Virtual Approver triggers, just as the maps show all workflow events and routing. To determine whether Virtual Approver is involved in a particular workflow application, check the SaveEdit and Workflow PeopleCode. If the PeopleCode uses Virtual Approver, you can identify the approval rule set being used.

Virtual Approver Templates

This PeopleSoft application delivers applications with some of the most common approval processes already set up. For example, PeopleSoft Payables uses a Virtual Approver-based business process to streamline voucher processing. In many cases, you must adapt an existing process, rather than develop a new one.

To adapt the approval rules for an existing business process, open the approval rule set for that process and update it with the rules that apply to your business. Because approval rule sets are managed objects within PeopleSoft Application Designer, the PeopleSoft upgrade tools help you manage upgrades. That’s the advantage of the table-driven approach to approval processing.

User List Roles for Organizational Levels

Some of the Virtual Approver processes that are delivered with PeopleSoft applications use user list roles that PeopleSoft has already defined: EMPLOYEE, MANAGER, VICE PRESIDENT, and so on. Virtual Approver uses these roles to specify the levels of authorization authority that a user has.

Although PeopleSoft delivers these default roles, you must make sure that the set of roles accurately reflects the levels in your company and that they’re assigned to the appropriate users.

Understanding Approval Rule Sets

An approval rule set is a workflow map representing the criteria for determining which approvals are required for a transaction. The components of the map are individual approval steps: one for each level of approval.

Subsequent sections discuss how to:

• Create approval rule sets.

• Define approval steps.

• Maintain approval rules.

Note. The Approval Rule Properties dialog box, Virtual Approver, and some currency-related PeopleCode functions depend on a set of database objects that do not exist in the PTSYS database. The set of database objects includes: PS_RT_DFLT_VW, PS_RT_TYPE_TBL, and RT_TYPE_LANG. These database objects currently reside in the Common Components project, which is named EO_COMMON. If you require these features to function within the PTSYS database, then you must transfer these tables into the PTSYS database using the upgrade copy feature in Application Designer.

Creating Approval Rule Sets

This section discusses how to:

• Create approval rule sets.

• Specify approval rule properties.

• Specify additional approval rule properties.

• Make an effective-dated change to an approval rule set.

Except where specified, this process is the same, regardless of whether Virtual Approver or GetApprovers uses the approval rule set.

Creating an Approval Rule Set

To create an approval rule set:

1. In PeopleSoft Application Designer, select File, New.

2. Select Approval Rule Set and click OK.

3. Save the rule set and assign an effective date.

   Unless you specifically want to make the approval rule set effective at a particular time, use a standard effective date, such as 01/01/1900.

Specifying Approval Rule Properties

This section discusses how to specify approval rule properties.

To specify approval rule properties:

1. Open the Approval Rule Properties dialog box by selecting File, Definition Properties.

   The Approval Rule Properties dialog box appears, displaying the General tab.

2. Enter descriptive information about the approval rule set.

   Use the Icon Descr (icon description) field to specify a description that appears next to the rule set’s name in dialog boxes that list approval rule sets.

3. (Optional) Temporarily suspend the use of this approval rule set.

   Clear the Approval Active check box to prevent Virtual Approver from checking the approval rules. Instead, it automatically approves all transactions.

4. Specify whether users can approve their own transactions.

   Select Allow Self Approval if users are permitted to approve transactions that they entered. Selecting this option does not mean that transactions are automatically approved; self-approval is still subject to the person’s approval limits. For example, if managers can approve purchase requisitions up to 5000 USD, then a manager who submits a requisition for 7500 USD cannot self-approve that requisition, even if you allow self-approval.

Specifying Additional Approval Rule Properties

This section describes how to specify additional approval rule properties.

To specify additional approval rule properties:

1. Select the Use tab.

   Enter the name of the business process that is associated with this rule set.

   Although approval rule sets are not represented by physical icons on workflow maps (business processes and activities), the approval process that you’re defining is part of a workflow business process. Enter the name of that business process here. This information is required when you use Virtual Approver.

   When you add PeopleCode to call Virtual Approver from the transaction page, this business process is one of the input parameters.

2. Specify the event to trigger when all required approvals have occurred.

   Note. This information is for Virtual Approver only; the GetApprovers function disregards this information.

   In the On Authorized group box, enter an activity name (associated with the business process that you’ve specified) and event name to specify which event should be triggered when the transaction is fully approved. Virtual Approver triggers this event when final approval occurs. For example, after a purchase requisition is approved, it is logical to trigger an event that notifies a buyer that the approved requisition is ready to be fulfilled.

   PeopleSoft Application Designer enables you to deactivate individual business events. If you deactivate an event that Virtual Approver is supposed to trigger, the event isn’t triggered.

   An On Authorized activity or event is optional. Try to avoid using the same activity or event as on the individual step's On Pre-Approved field.

3. Specify currency units for the approval rules.

   Enter currency information only if the approval rules are based on monetary amounts in the transaction.

   Enter the currency code and rate type that are used in your approval rules. For example, if a rule requires approvals for amounts over 1000 USD, enter USD.

4. Specify the currency unit for the transaction.

   Specify the currency record and currency field name that store the currency code for the data to be evaluated. For example, to evaluate whether a requisition requires approval, you must know the amount of the requisition and the currency in which that amount is expressed.

   Note. If the currency that is specified for the transaction being processed is different from the currency that is specified for the approval rule, Virtual Approver performs the appropriate currency conversion before making the comparison.

5. Click OK to close the properties dialog box.

6. Add approval steps to the rule set.

7. Save the approval rule set.

Making an Effective-Dated Change to an Approval Rule Set

To make an effective-dated change to an approval rule set:

1. Open the approval rule set.

2. Select File, Save As.

3. Enter the new effective date.

4. Click OK.

   Now, a new object with the same name exists, but it has a different effective date. The different effective-dated versions of the rule set appear separately in the dialog box.

5. Modify the rules, as needed.

Defining Approval Steps

This section provides an overview of approval steps and discusses how to:

• Add a rule step to a rule set

• Define a rule step.

• Specify rule step rules.

• Specify rule step events.

Understanding Approval Steps

Rule steps are the individual approval steps. Approval rule sets incorporate one rule step for each level of approval that might be required.

When the person who submits something for approval has no self-approval authority, you do not need to include a step for that person. However, you may include a step for that user so that your graphical map more clearly documents the entire process. As long as that user has no authorization authority, Virtual Approver bypasses that user anyway.

If users who submit items for approval have some level of authorization, for example, users can self-approve amounts up to 100 USD. Then, the first rule step must represent that approval level.

Adding a Rule Step to a Rule Set

To add a rule step to a rule set:

Note. This process is the same, regardless of whether Virtual Approver or GetApprovers uses the approval rule set.

1. Click Approval Step on the toolbar.

2. Click the location on the approval rule set where you want the step to appear.

   An Approval Step icon appears where you clicked.

Defining a Rule Step

This section discusses how to define a rule step:

To define a rule step:

1. Double-click the rule step icon, or right-click it and select Item Properties.

   The Rule Step Definition dialog box appears.

2. Enter an icon description.

   Use the Icon Descr field to specify a description to appear in dialog box boxes that list this type of map. If you leave this field blank, the map name appears by default.

3. In the Route to Role list box, select the role that performs this step.

   The role that you select is the role of the user who approves items at this step and path. The system verifies this role against the row-level rule that you set up in a previous step before routing items. Select a user list role that corresponds to a level within your organization. In approval processes, a person’s level typically determines the approval authority.

   Note. The Virtual Router portion of Virtual Approver determines who should receive the work item based on the role that you specify here, with the query role that is assigned to the worklist in PeopleSoft Application Designer. The worklist's query role must accept a role name as a bind variable, as the standard route control roles do.

4. In the Equally Authorized Roles field, select all of the roles that are qualified to process the transaction at this step.

   For example, consider a purchase request process in which managers can approve transactions up to 25,000 USD. If a manager enters a request for 25,000 USD or less, Virtual Approver automatically approves it. Now, suppose that you also want to allow system administrators to self-approve up to 25,000 USD (if you allow self-approval). All you do is add SYSTEM ADMINISTRATOR to the Equally Authorized Roles box. System administrators don’t receive transactions routed to them, but they are treated as managers for the requests that they submit.

   You can also use this field for users who do not normally participate in the approval process, but who have the necessary authority to approve at this level. This can be useful for exception processing, for example, when the regular approver is unavailable or you need to approve a transaction outside the worklist. Be aware that even if an equally authorized user handles the approval, the worklist routing in the regular approver’s queue does not disappear.

   GetApprovers does not return information about equally authorized roles, only about users who actually perform approvals.

   Use the Add and Remove buttons to add users to or remove users from the Equally Authorized Roles box.

5. Specify what the user sees when a transaction requires further processing for approval.

   When a transaction needs further approval, Virtual Approver can:

   • Trigger the specified event to forward the transaction to the next step.

   • Display a message to the user, indicating that further approval is required.

6. Specify which of these actions Virtual Approver should take by selecting one of the options in the On Further Processing box on the right-hand side of the page. The default is Both.

   Workflow Only	If a transaction needs further approval, Virtual Approver forwards it on to the next step without informing the user.
   Message Only	The user sees a message indicating that the transaction needs further approval, but the transaction does not enter the workflow.
   Both	Virtual Approver displays a message asking the user whether to add the transaction to the workflow. If you select Message Only or Both, the message comes from the PeopleSoft Message Catalog. Use the Message Catalog setting to specify the set and number of the message that the user sees.

7. Specify whether the system can bypass this approval step if additional approval is required.

   In the Skip to Next Step group box, select when, if ever, the current approver should be ignored:

   Yes	If additional approvals are needed, the system always bypassses this approver. Use this option only when role users can self-approve certain transactions but do not ever approve other people’s transactions.
   No	This approval step is not skipped and the routing occurs, regardless of whether additional approvals are required. This step is omitted only when a prior approver was able to give final authorization.
   Only skip if cannot authorize	If additional approvals are needed (that is, this approver does not have final approval authority), the system skips this approver.

8. In the Appr Step (approval step) and Appr Path (approval path) fields, specify which step you are defining.

   Approval processes can have multiple steps (in sequence) and multiple paths (in parallel). The purchase request example following this procedure has several steps, but only one path. An example of a process with multiple paths is one in which requests must be approved by the department manager and an office manager before going to a vice president. Here is the sequence of steps and paths in this case:

   Step	Path	Route to Role
   1	A	MANAGER (DEPARTMENT)
   1	B	MANAGER (OFFICE)
   2	A	VICE PRESIDENT

   In this example, the system sends two worklist entries when a new request comes in: one to the department manager and one to the office manager. When both of the managers approve the request, the system forwards it to a vice president.

   Note. The easiest way to determine approval steps and paths is to consult the activity map for the business process for which you are defining approval rules.

   Note. The approval step definition allows for up to 99 steps to be available when you are defining an approval process in Application Designer. However, you can enter any step number required.

   Note. No mechanism in Virtual Approver exists by which the worklist entry is removed from other parallel approvers when using multiple steps in case of deny or recycle.

Specifying Rule Step Rules

This section discusses how to specify rule step rules.

To specify rule step rules:

1. Select the Rules tab to specify the approval parameters.

2. Specify which transactions the specified role users have the authority to approve.

   You can specify which transactions a user can authorize in the following three ways:

   • If approval requirements are based on a monetary amount, enter the criteria in the Amount Rule group box.

     The user can authorize transactions whose monetary amount is between the values in the Min (minimum) and Max (maximum) fields. The associated record and field specify the record and field containing the amount in the original transaction.

   • If approval criteria are based on a (non-monetary) quantity, enter the criteria in the Quantity Rule group box.

     The user can authorize transactions in which the (non-monetary) quantity is between the values in the Min and Max fields. The associated record and field specify the record and field containing the quantity in the original transaction.

   • If the approval criteria are based on the approver’s user data, enter the criteria in the Row Level Rule group box.

3. There are two methods of obtaining row level criteria: using a route control or a SQL object.

   • If you select Route Control, the range of transactions that the user can authorize is determined by the user’s route control profile. The system compares the value from the specified record and field with the user’s route control profile. If the value is in the range to which the route control profile gives the user access, the user can approve the transaction.

   • If you select SQL Object, the range of transactions that the user can authorize is based on other data in the database.

     Evaluate the data using a SQL program that you create as an Application Designer SQL object. After you create the SQL object, enter its name next to the SQL Object option. Enter bind variables used in the SQL program in Record and Field. At most, five record and field binds can be used.

     If SQL Object is selected, the worklist defined in the On Pre-Approved activity or event must be consistent with the Operator defined by the SQL Object. Be sure that the Route to Role matches the Operator rendered by the SQL Object.

     For example, if you use the PeopleSoft HRMS applications, which store extensive data on reporting relationships within the organization, you can use a SQL object to specify that a manager is authorized to approve only requisitions submitted by people in that manager’s department. Using order_hdr.deptid as the bind variable, you can use the following SQL program:

     Select a.oprid from psoperalias a, ps_dept_tbl b where a.emplid = b.emplid and⇒
      b.deptid = :1 

     Note. When using a SQL object as a row-level route control in an approval rule set, set the field map for worklist OPRID consistently.

   • You can specify more than one authorization rule for any rule other than SQL object. To add additional authorization rules, enter data in multiple grid rows. For example, you can base the routing on more than one route control field. The number in the Seq (sequence) field is changed incrementally for each rule that you add. You can also use multiple authorization types for a single step. In this case, the user can authorize only transactions that meet all of the specified rules for this step.

Specifying Rule Step Events

This section discusses how to specify rule step events.

To specify rule step events:

1. Select the Events tab to specify which business events are triggered, depending on the action of the approver at this step.

   At each step in an approval process, the person reviewing a transaction has three options: approve it, reject it, or send it back to the previous step (recycle). The Pre-Approved Activity/Event box specifies what happens when the person approves the request. You can also specify deny and recycle activities and events. For example, if a request is denied, you might trigger an event that sends an email message to the requester.

   If you don’t select an event for these actions, the system changes the status of the transaction, but doesn’t route it anywhere.

2. In the Pre-Approved Activity/Event group box, select the business event to trigger when this approver approves the transaction.

   For the first step in the process, this is the event to trigger when a user enters a new transaction. For subsequent steps, it is the event to trigger when the user who is performing the current step approves the transaction, but it requires further approval. In either case, the event must forward the transaction to the next step. These settings are required; you must identify a pre-approved activity and event.

   Define each event as part of an activity in PeopleSoft Application Designer. Select the activity name in the Activity list box and the event name in the Event Name box.

   Note. Virtual Approver triggers this event when the transaction requires further approval, that is, when the user who approves it does not have sufficient authority to make a final approval, according to the rules that you defined on the previous page. If the user has the authority to approve the transaction, Virtual Approver triggers the Approval Activity/Event for this approval rule set, which you specify in the properties for the overall approval rule set.

3. Specify which events to trigger if the user denies or recycles the transaction.

4. Repeat this entire procedure for each step in the approval process.

5. Click OK to close the properties.

Maintaining Approval Rules

Maintain approval rules using the Approval Step Maintenance (APPR_STEP_MAINT) component.

This section provides an overview of approval rule maintenance and discusses how to maintain approval rule steps.

Understanding Approval Rule Maintenance

Over time, your business rules might change. Perhaps you once required managerial approval for purchases over 100 USD and now you require approval only for purchases over 500 USD.

You can maintain approval rules in the same place that you create them: on the rules tab of the rule step property sheet. If you prefer to expose the rules to your users so that they can update the rules without using PeopleSoft Application Designer, you can use the Approval Step Maintenance page.

Page Used to Maintain Approval Rules

Maintaining Approval Rule Steps

To access the Approval Step Maintenance page, select PeopleTools, Workflow, Approvals, Maintain Approval Rules.

To maintain approval rules:

1. Search for an existing approval rule set, approval path, and approval step.

   Use the standard search method to identify your approval rule and access the Approval Step Maintenance page.

   Note. This page shows only one rule at a time; the page does not provide an overview of how all of the rules fit together in the approval rule set. Therefore, to use this page effectively, users must be able to identify the approval rule sets and their embedded paths and steps.

2. Update the amount rules.

   If approval requirements are based on a monetary amount, enter the amount rules.

   The user can authorize transactions whose monetary amount is between the values in the Minimum and Maximum fields.

   Note. The Minimum and Maximum fields support 23.3 decimal precision. That is, 23 digits can appear to the left of the decimal, and 3 digits can appear to the right of the decimal.

   The monetary amount that is evaluated comes from the associated Record and Field fields. Normally you do not change these values on the page, as doing so might require additional modifications that can be made only in PeopleSoft Application Designer.

3. Update the quantity rules.

   If approval criteria are based on a (non-monetary) quantity, enter the quantity rule.

   The user can authorize transactions whose monetary amount is between the values in the From Quantity and To Quantity fields.

   The quantity that is evaluated comes from the associated Record and Field fields. Normally, you do not change these values on the page, as doing so might require additional modifications that can be made only in PeopleSoft Application Designer.

4. Review all of the rules.

   If you specify more than one authorization rule for any step, users can authorize only transactions that meet all of the specified rules.

5. Save the page.

Triggering Virtual Approver Routings

This section provides an overview of virtual approver routings and discusses how to:

• Add workflow work pages.

• Add Virtual Approver PeopleCode.

Understanding Virtual Approver Routings

After you create approval rule sets, the steps for developing a Virtual Approver approval process are basically the same as for any other business process. You define roles, events, and routings. When you set event triggers, however, instead of using the TriggerBusinessEvent PeopleCode function, you use a pair of functions that trigger routings based on the approval rule set that you specify. To access these functions, you must first add special work pages to the component where the event is triggered.

Adding Workflow Work Pages

Every component that uses Virtual Approver PeopleCode must include the pages WF_FUNCTIONS_01 and APPR_WRK_01. These special work pages load several important Workflow PeopleCode functions into memory. For example, if you’re using route controls, WF_FUNCTIONS_01 enables the system to determine which route control types are relevant for the event that you’re triggering.

To add work pages to a component:

1. In PeopleSoft Application Designer, open the component.

2. Add WF_FUNCTIONS_01 and APPR_WRK_01 to the list of pages in the component.

3. Save the component.

Note. Usually, after adding a page to a component, you use PeopleTools Security to grant users access to the page. However, because WF_FUNCTIONS_01 and APPR_WRK_01 are work pages, you do not want users to see them or be able to access them.

Note. The derived/work record APPR_FIELDS_WRK includes the field PREV_ROLEUSER, which is typically used to identify the previous approver if the process is recycled. If your approval process includes parallel paths, note that if the process recycles from the step above the parallel path, PREV_ROLEUSER is the user who approved at the highest path of the previous step. If this person recycles the process again, it will go through the lower path on the same step, then to the prior step. If the process recycles from a parallel step without an approval, then PREV_ROLEUSER is the user who approved the previous step, and the application must take care of the worklist on the other path of this step.

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:

   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.

Reviewing Approval History

To review approval history, use the Approval Instance Log (APPR_INST_LOG) component.

The Approval Instance log in the Workflow Administrator enables you to see the history of a work item as it passed through the steps of the approval process. You can determine which role users reviewed the item, what action they took, and the item’s status.

This section discusses how to review approval instances.

Page Used to Review Approval History

Reviewing Approval Instances

Access the Approval Instance Log page.

To review the approval history of a work item:

1. Enter the approval instance ID of the work item in which you are interested.

   A work item’s approval instance ID is part of its worklist entry. Find it by viewing the worklist entry on the Worklist page (if you have access to the worklist) or by using the Worklist Monitor.

   When you enter the approval instance ID, the Approval Instance Log page displays the data for the specified item.

2. Scroll through the steps in the process.

   When you first open this page, it displays information about how the work items entered the workflow (step 0, with the status Initiated). Scroll to review information for each subsequent step. The approval instance status for the last available step is the current status of the work item.

Using GetApprovers PeopleCode

GetApprovers PeopleCode determines the entire list of required approvals based on the rules that are defined in an approval rule set. GetApprovers evaluates all approval steps at once so that you receive a complete list of approvers from the entire approval chain.

Typically, you include GetApprovers in the Workflow PeopleCode for the transaction that requires approval.

GetApprovers

Syntax

GetApprovers (approval_rule_set, evaluation_fields_rowset, approvers_rowset, approvers_record)

Description

The GetApprovers function:

• Evaluates each step in the approval rule set.

• Ignores a step when the rules for the step indicate that no approver is necessary.

• Obtains the role users for a step when the rules for the step indicate that an approver is required.

  GetApprovers identifies the role users using the method defined in the step: with either a SQL object or a route control.

After every step has been evaluated, the results are returned to the calling program as a rowset object.

Parameters

Returns

Returns a rowset with the following data for each required approver:

• ROLEUSER

• ROLENAME

• STEP

• PATH

GetApprovers also inserts this data into a record that you specify.

Example

GetApprovers("ORDER_APPROVAL", GetLevel0(), GetLevel0()(1).GetRowset(Scroll.APPR_⇒
USERLIST), "APPR_USERLIST")