rp hcmrs approvals framework1

Recruiting Solutions 8.9 Approvals Framework

By: Donald Knapp April 2005

PeopleSoft Red Paper Series

Recruiting Solutions 8.9 Approvals Framework

Copyright © 2005, Oracle. All rights reserved. The information contained in this document is proprietary and confidential to Oracle. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Oracle. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle, JD Edwards, and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

.

3

Table of Contents

TABLE OF CONTENTS............................................................................................................................................................. 3

INTRODUCTION........................................................................................................................................................................ 3 Structure of this Red Paper......................................................................................................................................................... 3 Related Materials ......................................................................................................................................................................... 3

OVERVIEW................................................................................................................................................................................. 3

ASSUMPTIONS........................................................................................................................................................................... 3

APPROVALS TOUR................................................................................................................................................................... 3 The Players ................................................................................................................................................................................... 3 The Installation Options.............................................................................................................................................................. 3 The Job Opening .......................................................................................................................................................................... 3 The Routing .................................................................................................................................................................................. 3 The Approval Actions.................................................................................................................................................................. 3

Examples of the Approval Actions ............................................................................................................................................ 3

FUNCTIONAL DESIGN ............................................................................................................................................................ 3 Basic Functional Use Cases ......................................................................................................................................................... 3

TECHNICAL DESIGN ............................................................................................................................................................... 3 Application Integration ............................................................................................................................................................... 3

Identify application’s main (header) record ............................................................................................................................... 3 Decide whether or not to support line-level approvals .............................................................................................................. 3 Create the cross-reference record, and the underlying table ...................................................................................................... 3 Identify the component and page to be used for the approvals UI............................................................................................. 3 Define an application class for event handling .......................................................................................................................... 3 Register the application with the AWE...................................................................................................................................... 3 Code the launching component.................................................................................................................................................. 3 Code the approving component ................................................................................................................................................. 3

Events and Event Handling......................................................................................................................................................... 3 Interpreting Events ...................................................................................................................................................................... 3

FUNCTIONAL IMPLEMENTATION...................................................................................................................................... 3 Approval Framework Administration Components................................................................................................................. 3

Approval Transaction Registry .................................................................................................................................................. 3 Approval Process Definition ...................................................................................................................................................... 3 User List Definition ................................................................................................................................................................... 3

Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Administration Monitor ............................................................................................................................................................. 3 Approver Authorization ............................................................................................................................................................. 3 Escalations and Timeouts........................................................................................................................................................... 3

Concepts........................................................................................................................................................................................ 3 Criteria ....................................................................................................................................................................................... 3 User Lists ................................................................................................................................................................................... 3 Steps ........................................................................................................................................................................................... 3 Paths ........................................................................................................................................................................................... 3 Stages ......................................................................................................................................................................................... 3

Approval Process Configuration ................................................................................................................................................ 3 Approval Process Definition ...................................................................................................................................................... 3

Approval Notifications................................................................................................................................................................. 3 Notification Templates............................................................................................................................................................... 3

Escalations and Timeouts ............................................................................................................................................................ 3 Escalation and Timeout Settings ................................................................................................................................................ 3 Running Escalations and Timeouts ............................................................................................................................................ 3 SMTP & URL Configuration..................................................................................................................................................... 3

Administration Monitor .............................................................................................................................................................. 3

OBJECT DRILL DOWN ............................................................................................................................................................ 3 API’s (Application Classes, CI’s, Views) ................................................................................................................................... 3

Package Diagram (HMAF_AWE) ............................................................................................................................................. 3 Common Application Classes: ................................................................................................................................................... 3 Recruiting Solutions Module Specific Classes .......................................................................................................................... 3 Recruiting Solutions API Views ................................................................................................................................................ 3

© Copyright Oracle Corporation 2005. All rights reserved. 5


Introduction

This Red Paper is a practical guide for technical users, installers, system administrators, and programmers who implement, maintain, or develop applications for your PeopleSoft system. In this Red Paper, we discuss guidelines on how to diagnose a PeopleSoft Online Transaction environment, including PeopleSoft Internet Architecture and Portal configuration. Configuration of Batch processes is not covered in this document.

Much of the information contained in this document originated within the PeopleSoft Global Support Center and is therefore based on "real-life" problems encountered in the field. Although every conceivable problem that one could encounter with Tuxedo, the PeopleSoft Application Server, or your web server is not addressed in this document, the issues that appear in this document are the problems that prove to be the most common or troublesome.

STRUCTURE OF THIS RED PAPER

This document provides detailed information regarding the configuration, and technical components of the PeopleSoft Approval Framework. This paper is intended to give interested parties a thorough understanding of how to implement the recently adopted SCM Approval Framework into their HCM application. Utilizing this common framework offers many significant benefits to HCM, our customers, and PeopleSoft as a whole.

These benefits include:

Reduced number of specific approval process solutions in HCM, thus reducing our maintenance burden. Frees up more development resources for new feature development.

Increased quality, usability, flexibility, and consistency for our customers. The SCM process far exceeds the capabilities of our existing solutions. Using the same framework across PeopleSoft require our customers to learn one process instead of many.

Single framework across the organization that allows us to focus our development efforts, leading to greater feature content and quality.

PeopleBooks should provide additional detail to help configuration.

Important Note: Read this Entire Document Before starting your Implementation or Configuration.

Keep in mind that PeopleSoft updates this document as needed so that it reflects the most current feedback we receive from the field. Therefore, the structure, headings, content, and length of this document is likely to vary with each posted version. To see if the document has been updated since you last downloaded it, compare the date of your version to the date of the version posted on Customer Connection.

RELATED MATERIALS

This paper is not a general introduction to environment tuning and we assume that our readers are experienced IT professionals, with a good understanding of PeopleSoft’s Internet Architecture. To take full advantage of the information covered in this document, we recommend that you have a basic understanding of system administration, basic Internet architecture, relational database concepts/SQL, and how to use PeopleSoft applications.

This document is not intended to replace the documentation delivered with the PeopleTools 8 or 8.14 PeopleBooks. We recommend that before you read this document, you read the PIA related information in the PeopleTools PeopleBooks to


© Copyright Oracle Corporation 2005 All rights reserved. 6

ensure that you have a well-rounded understanding of our PIA technology. Note: Much of the information in this document eventually gets incorporated into subsequent versions of the PeopleBooks.

Many of the fundamental concepts related to PIA are discussed in the following PeopleSoft PeopleBooks:

• PeopleSoft Internet Architecture Administration (PeopleTools|Administration Tools|PeopleSoft Internet Architecture Administration)

• Application Designer (Development Tools|Application Designer)

• Application Messaging (Integration Tools|Application Messaging)

• PeopleCode (Development Tools|PeopleCode Reference)

• PeopleSoft Installation and Administration

• PeopleSoft Hardware and Software Requirements

Additionally, we recommend that you read the BEA documentation (in HTML format) delivered with the BEA CD-ROM, to gain a thorough understanding of the BEA products that PeopleSoft uses, Tuxedo, Jolt, and WebLogic Server 5.1. Refer to your PeopleSoft Installation and Administration book for directions on accessing the delivered BEA documentation.



Overview

The purpose of this document is to provide a guide to the Approval Framework feature. It will provide the reader with an understanding on what and how to integrate the Approval framework within a PeopleSoft application.

It will take a HCM Use Case from conception to Implementation.

It is for a technical audience that is familiar with basic Internet and enterprise architecture concepts and is intended to provide the reader with a general understanding of the Approval Framework.

Assumptions

Before continuing with this document, the reader must be familiar with the PeopleTools.

Skill Description

Application Packages

You can create Application Packages in PeopleSoft Application Designer. These packages contain application classes (and may contain other packages also). An application class, at its base level, is just a PeopleCode program. However, using the Application Packages, you can create your own classes, and extend the functionality of the existing PeopleCode classes.

Application Designer PeopleSoft Application Designer is an integrated development environment that enables you to work with the numerous definitions of a business application in a single work area.

Data Mover

PeopleSoft Data Mover enables you to perform the following tasks:

1. Transfer application data between PeopleSoft databases.

2. Move PeopleSoft databases across operating systems and database platforms.

3. Execute SQL statements against any PeopleSoft database, regardless of the underlying operating system or database platform.

4. Control database security and access.

5. Create, edit, and run scripts. These scripts may include any combination of SQL commands and Data Mover commands for exporting and importing data.

Note: For more information on the above topics, please refer to PeopleBooks.



Approvals Tour

The approvals engine ushers transaction requests through a defined approval process. End users see little of the engine itself, and nor should they: requesters and approvers care mainly about the pending approval, not the engine, which routes the request to approvers in a set, sequence.

To show the engine in action, then, we show an application—Recruiting Solutions (Job Openings)—and its use of the approval engine. Recruiting Solutions uses the Approval Engine for two functional areas: Job Openings and Job Offers. For the purposes of this tour, we will focus on Job Openings.

But to be absolutely clear about it from the start, we want to emphasize that the approval engine is generic, and any application whose transactions need approval can use the same features we illustrate using Recruiting Solutions.

THE PLAYERS

In our examples, we will encounter the following players repeatedly:

1. Hiring Manager: Betty Locherty

2. Recruiter: Douglas Lewis

3. Hiring Manager Supervisor: Jean Parsons

4. Approval Administrator: Vicky Adler

THE INSTALLATION OPTIONS

Navigation: Set Up HRMS > Install > Product and Country Specific: Recruiting Installation

Approvals are not required for the Job Opening/Job Offer in Recruiting Solutions. There are Installation Options, which can be set to allow Approvals. When the installation option is enabled then the corresponding approvals functionality will be available.

Scroll down to the Approval Required section:

Figure 1

There are four check boxes available:

1. Standard Requisition: Approvals enabled on Job Requisitions

2. Continuous Job Opening: Approvals enabled on continuous Job Openings



3. Job Offers: Approvals enabled on Job Offers

4. Optional Works Council: Approval enabled for Works Council, Job Offers must also be enabled.

THE JOB OPENING

Navigation: Recruiting: Create New Job Openings

For the most part, we will show the same scenarios repeatedly. Betty will create a requisition. To introduce the functional pages, we show a simple requisition being created in Figure 2, Figure 3 and Figure 4 below.

Enter the required Opening information and select continue.

Figure 2

Select the Hiring Team link and enter a Recruiter and Hiring Manager. Then Save and Submit the Job Opening.



Figure 3

Select the Approvals hyperlink to access the Approval Process Monitor.

Figure 4



THE ROUTING

The Approvals Framework allows routing notification via two methods (email and worklist). However, in Recruiting Solutions there is a 3rd option, which is the Pending Approvals page. Below is an example of all three methods.

Figure 5

Figure 6

Figure 7

The link from all three routing paths will take the user to the Job Opening, where they can take action on the Job Opening approval status. Figure 8, represents the Job Opening approval monitor where the approval action is taken. The 3rd routing



path, which is displayed in Figure 9, can also do direct Approval and Denial. Using the checkbox and the appropriate dropdown value, the Job Opening can be approved or denied.

Figure 8

THE APPROVAL ACTIONS

There are a handful of Actions that can be taken on a Routed Job Opening. The Approval Framework supports the following:

Approve

Click to approve the job opening. When final approval is reached the system changes the job opening status from Pending Approval to Open.

Pushback

Click to send a notification to the previous approver telling them the job opening needs to be changed.

Deny

Click Deny to reject the job opening and set the job opening status to Denied. However, the originator of the job opening can later resubmit the job opening.

Resubmit

When a Job Opening has been Denied, the originator (Hiring Manager in out example) can resubmit the JobOpening. This creates a new Approval chain, and routing.

The Job Opening also has functionality setup to override the Approval Process. Overriding the Approval Process terminates all pending actions and routings for the current approval instance. Only users with a permission list defined as Recruitment Administratror under Recruiting Row Level Security have the permission to override. Override is accomplished by using the Override Approval dropdown under the Approval Monitor, on the Approval page. For Job Openings there are two options (All



Approved and Denied). The All Approved set the Job Opening status to Open and Denied set the Job Opening status to Denied. An example of this is displayed in Figure 16.

Note: For more information on setting Recruitment Administrator override privielges via Recruiting Row Leve Security, please see the Peoplesoft Enterprise HRMS 8.9 Applications Fundamentals Peoplebook.

Examples of the Approval Actions

Using the example started in Figure 1, we will now go through an example of each of the above actions.

Approve

For the first Approval Step, Figure 8, the Hiring Manager Supervisor is pending. The first Step approver has two options Approve and Deny. Figure 9, is an example of Jean Parsons (Hiring Manager Supervisor) approving the Job Opening. Upon approval, the Job Opening is routed to the next step, as is display below. The Recruiter Group is now set to pending.

Figure 9

Aside from the first step in the approval chain there will be three approval options available: Approve, Pushback and Deny. We saw an example of ‘Approve’ above in Figure 9. Next we will show an example of ‘Pushback’. The ‘Pushback’ status is used when the next approver in line wants more information or questions the approval decision of the step one approver. This is displayed in Figure 10.

Pushback

Select the Pushback button to send back one step. As can be seen below, Douglas Lewis (Recruiter Group) has pushed back to Jean Parsons (Hiring Manager Supervisor). With the comments entered into the Approval Comments History.



Figure 10

Deny

Next lets look at an example of Deny. Following the current approval chain, the Job Opening has been routed back to Jean Parsons (Hiring Manager Supervisor). Jean accesses the Job Opening via one of the methods identified in section on Routing. Figure 11 is the view Jean Parsons is displayed with.

Figure 11

Jean Parsons now must decide whether to Approve or Deny the Job Opening. For our example we will go with Deny. So Jean Parsons enters comments and selects the Deny button. As shown below in Figure 12, Jean Parsons has denied the Job Opening. This is visibly identiful by the Denied status displayed on the Approval Monitor as well as the Job Opening Status (Figure 13).



Figure 12

Figure 13

Resubmit

Next we will demonstrate the resubmit option. Although the Job Opening has been Denied the originator (Betty Locherty) can Resubmit the Job Opening. Betty Locherty logs in and searches for the Job Opening (10193). Once found she enters the Job Opening and uses the Approvals hyperlink to get to the Approval page (Figure 14). By selecting the Resubmit button, the Approval Process is started again. Figure 15, diplays the new approval chain that is identical to the original.



Figure 14

Figure 15

Approval Override

For the next example (Approval Override), we will continue using the Job Opening 10193. Currently it is in a Pending Approval status, as it was resubmitted in the previous example. For this example we log in as Betty Locherty, who is the Hiring Manager and has Recruitment Administrator privileges in her Recruiting Row Level Security permission list. Betty Locherty navigates to the Job Opening and then to the Approvals page. Figure 16, displays Betty Lochery’s approval options. As you can see there are two options (All Approved and Denied), both of which will terminate the Approval Process and set the Job Opening status accordingly. For our example we will set the status equal to All Approved. See Figure 17, for details. As you can see both of the steps in the approval chain have been terminated and the Job Opening status has been set to Open.



Figure 16

Figure 17

Material Change

The final example is the Material Change functionality. In the Job Opening there are a set of fields, that when changed, will trigger a Material Change. A Material Change is something that impacts the Approval Process. So while a Job Opening is still in Pending Approval status, and one of these fields is modified, the Approval Process is restarted from the beginning.



Below is a list of these fields for the Job Opening:

Target Openings From Salary Grade Standard Hours

Job Code To Salary Grade Requisition Type

Position Number Full-Time/Part-Time Area of Consideration

Salary Administration Plan Regular/Temporary Salary Range From

From Salary Grade From Salary Grade Standard Hours

Salary Range To Pay Frequency Citizenship Status

Functional Design

Having seen the approvals tour, the details are now called for. But before the details can make sense, the reader must understand the requirements which drove this engine.

BASIC FUNCTIONAL USE CASES

The basic use cses supported by Recruiting Solutions run as follows:

1. Customer’s business analyst defines an approval process

a. The business analyst defines a different approval process for each application, which has integrated with the AWE.

b. The analyst establishes setid, effective date and effective status for each approval process.

2. User submits a request

a. User creates an application transaction (such as a requisition, expense report, etc.)

b. The application code initializes the approval workflow engine API objects, and checks whether that particular transaction has already been submitted for approvals, and whether or not it was previously approved or denied. As appropriate, the application presents the user with a “submit” or “resubmit” button. (The application could also choose to make a pending request non-editable.)

c. The user clicks the submit button.

d. The approvals workflow engine code instantiates and launches the approval process, creating worklist entries for approvers and reviewers, sending out e-mail notifications, etc. as configured.

e. The AWE API objects change state to indicate successful launch, and application code notes the change and disables the submit button.

3. Approver examines his worklist

a. A user for whom a request is pending approval examines his worklist, and sees an entry identifying the request, with a link to take him to a page where the request can be examined, and either approved or denied. The user clicks the link.



b. The approval page for that application opens. The application code initializes approval workflow engine API objects, and from those objects learns whether or not the user in question has that particular transaction pending his approval or review.

c. Accordingly, the application shows details of the transaction. If the user is an approver, then the application code shows buttons to indicate approval or denial.

d. The user approves, the application code makes the appropriate API calls on the AWE objects, and the next approver gets routed.

e. The AWE withdraws the worklist entry for this approver, and others as appropriate.

4. Approver denies a request

a. An approver follows use case 3 above

b. The approver denies the request.

c. The AWE marks the request as denied (in its own state tables), and halts further processing on that approval process. Any worklist entries for pending approvers are withdrawn.

d. The application is notified of the denial.

5. The last approver approves a request

a. The last approver enters the approval component, and follows use case 3 above.

b. The approval workflow engine code recognizes the end of the approval process, updates its internal state, and notifies the application of that fact. The application code takes appropriate action.

c. Worklist entries get cleaned up.

Technical Design

We spelt out the above use cases in some detail to set the context for the design descriptions, which follow. There are, of course, many more use cases, which can become especially involved. But the use cases above are enough to establish the main architectural features of the AWE; the other use cases spell out more details within the same framework. In short, the other use cases will be variations on the theme laid out above.

APPLICATION INTEGRATION

This section will be of the greatest interest to application developers integrating with the AWE. Each application’s needs vary, but the broad outlines will remain the same. The variation will all be encapsulated into PeopleCode in three places: the launching component, the approval component, and the event handler. Before the Functional Analyst can configure the Approval Process, the application must be integrated with the AWE.

Listed below are the necessary steps, in the approximate order in which this needs to be done. We discuss under each item some issues to be considered.



Identify application’s main (header) record

This is pretty straightforward. For instance, Recruiting Solutions uses the HRS_JOB_OPENING, the Job Opening record. Still, the obvious choice is not always the right one.

Decide whether or not to support line-level approvals

Most processes in HCM, if not all, will not use line level approvals. If yes, then identify the line-level record.

Line level approvals are naturally attractive for certain applications, including eProcurement and Expense Sheet. But there are many subtleties to consider.

a. Do customers deny some line items and approve others? If not, line-level approvals are just needless complexity.

b. If a request were partially denied, how would the customer like to proceed? Would they be willing to resubmit the whole transaction again?

c. If denied line items are to be resubmitted, is it possible to define a view on the line-level record which would exclude previously approved items? If so, would that suit the customers’ needs better?

d. If line- and header level approvals work in two stages in the approval process, what should the implications of a line-level denial be? For instance, in an expense sheet, presumably a line-level denial of one expense item should lead to a reduced total on the header (or overall transaction). Note that this might affect subsequent routing per the business logic, but the AWE does not do dynamic re-routing! In such circumstances, it may be better not to allow line-level approvals in the first place!

Create the cross-reference record, and the underlying table

This is straightforward, with one subtlety to keep in mind: if line-level approvals are supported, then the cross-reference record should include all of the line-level record’s keys (and, as noted above, the assumption is that the line is a child of the header in the sense of including all the header’s keys).

The AWE must have means to track the application transaction’s keys, and correlate these with approval process instance keys. This is so that, given the transaction keys, the AWE knows which running approval process (if any) is being referenced.

The figure below shows the cross-reference record for Recruiting Solutions Job Opening. Note that the Job Opening record keys are included, but they are not keys of the cross-reference record!

Figure 18

The first “field” in the figure above is a sub record, specifically one that contains the AWE key fields. It also contains other fields we need to keep track of the approval process. The figure below shows that sub record.



Figure 19

Identify the component and page to be used for the approvals UI

Note: The approvals page belongs to the application, not to the AWE.

The constraint here is that the component’s “Get” keys1 should be exactly the keys of the header record. This is because the worklist is consolidated at the header level, and the URL in the link pointing to the approval component has only the header keys available to it.

For the Job Opening implementation we use the HRS_JOB_OPENING component.

Figure 20

1 “Get” keys are like search keys. If the search keys are under specified, the selection isn’t unique, and the user gets to pick one of the possibilities. Get keys, in contrast, are a complete set of search keys, so that exactly one result is specified, and the user is directly taken to the component and page.



Define an application class for event handling

The basic idea is very simple. The AWE includes an application class called the ApprovalEventHandler. This class defines several methods, which the AWE calls to communicate events. Application developers extend this class, and override the base class’ methods that are of interest to them. Before this works the AWE needs to know the fully qualified name of the application’s event handling class.

For the Job Opening implementation we use the HRS_AWE_EVNT_HNDLR.HRS_JOB_OPENING.JobOpeningHandler class.

Figure 21

The main challenge in correctly coding the event handler is to understand the AWE’s event model. That is such a large topic that there are two sections (Events and Event Handling and Interpreting Events) reserved for it.

Register the application with the AWE

All of the information described in the steps above is stored on the transaction registry. In addition, there is e-mail notification and notification template configuration to be done. This is described elsewhere, in the section Approval Process Configuration.

The approval transaction registry is the interface application developers use to register an application with the approval workflow engine. Transactions are processes that PeopleTools perform for applications. Transactions that require approvals are candidates for being linked to approval workflow engine. You use the Approval Transaction Registry page to link the components, event handler, records, and classes that you created into the approval process for an application transaction, such as a Job Opening or Job Offer. Application developers register the main records and components that make up the transaction.

Approval Process Id Enter a name the system uses to track this approval workflow process for a transaction. You can also enter a description for the approval process.

Object Owner ID Select the PeopleSoft application to which this object belongs.

Cross Reference Table Select the table used to manages application specific transaction records and associate them with the approval process run time instances.

Approval User Info View (approval user information view)

Select the table from which you want to extract personal contact information for the approver. This is the information that appears when you use the approval status monitor to display personal information. These values are set up in the Application Designer.

Ad Hoc User List Define a user list to be used for additional Adhoc approvers that are manually added to the approval process



Enable Notifications Select this check box to have the Approval Engine send out email notifications.

Wrklist Approval Component

Menu Name Select the menu name that contains the component you want the notification recipient to link to. This identifies where the person should go upon notification. If you do not enter values, the recipient is sent to the same menu and component that is defined for the worklist.

Approval Component

Select the component on which the approval is going to be based. You must also create a URL to send to the job opening or job offer approval page for the job opening.

Approval Event Handler Class

Root Package ID

Select the parent application class through which events are exposed. This defines the action to take based on events.

Path Select a path that uses a specific class within the root package.

Adhoc Approver Logic Class

Adhoc Package Select the ad hoc application class package that you want to use for ad hoc approvals.

Thread Descr (thread description)

Select a thread description that will be used to identify the description that is used for the status monitor display.

Adhoc Class Select the ad hoc application class path. This defines more specific classes for ad hoc approvals.

Class Path Identify the class path for the thread description class.

Transaction Approval Levels

Use this group box to define if the transaction is to be approved at the header or line level and what level the application supports. You define:

• The levels that are enabled by the application for approvals. The first row will always be the header level.

• The database table that represents this transaction level.



Figure 22

Code the launching component

The launch component can collect the necessary information and instantiate the LaunchManager API application class provided by the AWE (In HCM we use a Wrapper Class to interact with this Class, details later). Of course, an application could choose to bypass this class, and interface with the AWE at a lower level. But this is unlikely to be helpful in most cases—we have taken care to code the LaunchManager application class to make it maximally useful to application developers.

First of all, application developers need to gather the information they need to initialize the LaunchManager. Of the parameters the constructor takes, three are available and known even at coding time:



a. The approval process id, established when registering the application as describe above

b. The setid, obtained via an application-specific mapping

c. The operator id of the person on whose behalf the request is being submitted. Usually this would be the person logged in, but the AWE does not make this assumption, leaving the application free to support “on behalf of” functionality.

The fourth parameter is the header record instance for the request to be submitted. This is readily available in the launching component.

Once the LaunchManager is instantiated, its properties and methods provide all the information and API calls the application needs to preview and launch approval workflows.

We provide the following recommendations in managing the lifecycle of the LaunchManager object:

a. Instantiate this class in the Component PreBuild/PostBuild event PeopleCode. This class’s constructor takes arguments mostly known to the application developer development time. The only runtime-specific argument is a header record instance. But the AWE is only interested in the header key values, and these values are known at Component PreBuild/PostBuild.

b. Having initialized LaunchManager at Component PreBuild/PostBuild, developers are now in a position to correctly decide whether (and which) approval-related UI buttons to display. For instance, if the hasAppDef property is false, then there are no valid, effective approval process definitions for this application, and no buttons should be displayed to submit the transaction for approval.

c. Since many applications start new transactions without a primary key value assigned (“NEW” is a typical temporary value used by applications, the method SetHeader() takes a new header record instance to replace the one with which the LaunchManager object is created. The AWE, of course, validates the new header record instance by re-examining its tables to ensure that no approval process can be launched if an earlier process is already running.

Finally, note that while the approval process runs off a header record instance in memory, there are other parts to the AWE that often look directly into the database. These are configured criteria and user lists. Since these can be arbitrary SQL queries, and they are more likely than not to refer to the application’s header and line records, it is critical that the application records be saved to the database before the approval process is instantiated (via either a PrepareToSubmit() call, or a DoSubmit() call on the LaunchManager).

We recommend that application developers implement the trigger to DoSubmit() via a work record field tied to a pushbutton. The button click should trigger a DoSave() call in Field Change PeopleCode, and the LaunchManager’s DoSubmit() method should be called from the field’s SavePostChange PeopleCode.

Example of the above process is displayed in the next set of Screen shots.

Job Opening Controller is called from the Job Opening PostBuild.

Figure 23



The Controller calls out to the Job Opening component business class, as part of the component initialization, to determine if approval is on. The Installation Option described in an earlier section determines this.

Figure 24

The initialization of the job opening approval process in done in the following class. The Job Opening component business class calls out to the Job Opening business class.



Figure 25

When the Job Opening is ready to be submitted for Approval, the Save and Submit button is used. This in turn calls the following code.

Figure 26

Code the approving component

Just as the LaunchManager application class helps application developers code the launching component, so the ApprovalManager application class helps in coding the approving component. Its properties and methods provide all the information the application developer needs to correctly meet the approver’s UI needs.

The coding of the approval component is trickier than that of the launching component, for the following reasons. Application developers need to handle the case where



a. The user in question is not an approver

b. The approval is pending at the line-level, with potentially multiple selections and actions to be indicated, and the display refreshed between each

c. An indicated action cannot be persisted because another approver acted in the meantime, thus making the display stale

d. The approver wants to enter comments

e. Pushback is enabled/disabled

We present a basic sequence of methods and properties to be queried:

a. First of all, consider the cases where user navigated to this component with a valid set of header keys, but there is:

• No approval process defined

• No approval process running

• No approval step is pending for this user

b. Find out whether header or line-level records are pending approval for the user. The AWE guarantees that line and header level cannot be pending at the same time for anybody.

c. If line-level records are pending, then the application needs to display the records in question. The ApprovalManager’s GetPending() method returns a rowset containing the pending records.

d. When indicating the approver’s action (approve/deny/pushback), the application needs to indicate the record on which the action is being taken. For header level approval, this is straightforward—there is only one header level record instance. For line level approvals, the application needs to have a means of allowing the approver to indicate the records and the actions. Typically, applications will display multi-select checkboxes in a grid, and buttons labeled “Approve”, “Deny”, etc. Alternately, there can be columns in the grid with such buttons for each displayed row. Either way, the application needs to carefully program the display to ensure that

• Only the pending records have the checkboxes or buttons enabled

• Once a particular pending record has been acted upon, its checkbox or button is no longer enabled, unless the record in question is still pending (yes, this is possible, see below)

• The application needs to refresh its display after the approver acts, taking care to handle the situation where something is still pending for the approver. In line-level approvals, the obvious possibility is that some lines are still pending. But even in header level approval, the current approver might still be left with a pending task after approving—he might be an approver on the very next step as well!

Note that the AWE handles its own persistence. This means that it issues SQL inserts and updates to the database. Application developers would be well advised not to trigger any component record changes at all. It isn’t necessary, and it can cause failures if the same records are touched by the AWE and the component! This isn’t very likely, since the AWE scrupulously avoids touching any records other than its own, but there is one potential source for overlap, which we explain below in the section on Interpreting Events.

The calls to the ApprovalManager’s DoApprove() and DoDeny() methods can occur in the context of a Field Change PeopleCode triggered by the usual button clicks.

In Recruiting Solutions, for the most part we use the same component as the Launch/Approval component. The only exception is the use of the Pending Approvals component.

The Job Opening component uses approval buttons for Approve, Pushback and Deny. These buttons in turn call the corresponding Field Change PeopleCode methods. Below is an example of the code used for Approve; however, virtually the



same code is used for Deny and Pushback. The only difference being deny uses DoDeny (&recJoCopy) and pushback uses DoPushBack (&recJoCopy).

Figure 27

The Pending Approval component uses a slightly different approach. Multiple Job Openings can be either Approved or Denied directly from the Pending Approvals grid, by using the dropdown actions. Since we are not working with a single approval instance, we loop through the selected rows and launch the appropriate approval manager.



Figure 28

EVENTS AND EVENT HANDLING

The AWE generates the following events during the life of an approval process:

OnProcessLaunch

This event triggers when an approval process launches on an application transaction.



OnStepActivate

This event triggers when a step is activated, meaning when the approval task queues to the approvers on that step. After this, the approvers can meaningfully approve or deny the request.

OnStepApprove

This fires when the minimum number of approvers (as configured) approves a step.

OnPushback

This fires when an approver pushes the approval back to the prior step, usually indicating a challenge to the previous approver’s okay.

OnReactivate

The reverse of pushback, this fires when the approver who received the pushback again approves, and the approver who had previously pushed back now again receives the approval task.

OnHeaderApprove

This event triggers only when an approver approves at the header level, and no more steps, paths or stages remain. It indicates that the approval process is over, and the request is finally approved. No further events will be communicated on this approval process, and the approval process itself is no longer running.

OnHeaderDeny

This event triggers when an approver denies the request at the header level. As noted earlier, any approver can deny, and that denial is final: no further approval routings are attempted at that point. The process ends, and all pending and as-yet-unrouted steps are terminated.

OnLineApprove

This indicates final approval, but at the line level. This notification is sent if and only if:

a. The last stage of the approval process was at the line level

b. The line in question was approved, and no more approvers remain in any step instance and path instance.

c. The approval process was configured to allow line-level actions (see above).

OnLineDeny

This indicates final denial, but at the line level. This notification is sent when an approver denies any line, and that line is not routed to any more approvers. The approval process continues routing other pending lines. If all the lines have been denied, then the approval process ends, even if later stage instances exist, even at the header level.



OnAllLinesProcessed

This indicates that the approval process is complete. It is triggered if and only if:

a. The last stage of the approval process is at the line level

b. All lines have been either approved or denied

c. At least one line has been approved

If the process has been configured to allow line-level actions (see above), then the method’s parameter arrays are empty, since OnLineDeny and OnLineApprove events will already have fired for the corresponding lines. If the process has not been configured to allow line-level actions, then the OnLineDeny and OnLineApprove events are suppressed, and in that case the OnAllLinesProcessed method’s parameters contain arrays of approved and denied records.

OnTerminate

A process is terminated only upon an explicit call from the application code to that effect; in that case, this event is triggered.

OnAdhocInsert

This event triggers when an Adhoc is inserted.

OnAdhocDelete

This event triggers when an Adhoc is deleted.

INTERPRETING EVENTS

When the engine encounters a particular situation, it triggers an event, which is received by the application’s event-handling application class object. The previous section showed how, given a particular situation, the AWE knows which event to fire.

The application programmer’s problem is a bit different: given that a particular event notification has been received, some information is explicitly given, but some other information is implied—but what? For each event, we describe both the explicit and implicit information to be gleaned from it. We also describe actions the typical application programmer might want to take with each event.

OnProcessLaunch

This event is called only on the launch of an approval process, and is therefore the first event to be called. Note that this does not mean that the header record in question has not been submitted for approval before. But if this is a resubmit operation, then the AWE guarantees that one of the “end process” events (OnHeaderApprove, OnHeaderDeny, OnAllLinesProcessed, or OnTerminate) will have been called on the earlier approval process instance.

This method will only be called in the context of the launching component.



OnStepActivate

This event method is called when a step instance activates (queues to its approvers). The first step instance of all the path instances of the first stage all activate when the approval process is launched; subsequent steps activate when their prior step is approved.

This method can be called in the context of the launching component, the approving component, or outside of any component at all.

OnStepApprove

This event is called when the configured minimum number of approvers approves a step. In general, it will be called in the context of the approving component. But it might also be called outside of any component context; see below.

OnPushback

This event is called when an approver pushes back to the prior step in its path. As with approval, this is usually called from the approving component, but not necessarily.

OnReactivate

Similar in every respect to OnActivate(), except that it always follows a Pushback from the step in question.

OnHeaderApprove

On receiving this event, developers can be sure that

a. The last stage of the approval process instance was a header level stage.

b. This will be the last event of this process instance. The process ends now.

c. The header is finally approved, and the application should take whatever action is appropriate on approval.

The last approver approving the header will usually trigger this event. But if the approval process evaluates to an empty process (all path criteria evaluate to false, for instance), then this event will trigger on launch, and hence in the context of the launching component! Once again, the best solution is to avoid all such potential conflicts: code the event handler to always go directly to the database, and code the approval page and component to make no changes to its component row sets at all.

OnHeaderDeny


a. A header-level approver has denied the request, Or All line-items have been denied at the line-level

b. This will be the last event communicated from the process. The process ends now.

c. Unlike the case with OnHeaderApprove, no assumptions can be made about what the last stage of the approval process was: a denial is final, whichever the stage in which it occurs.



OnLineApprove


a. The last stage of the approval process instance was a line-level stage

b. All approvers who needed to act on this line have approved

c. This line will not be routed to any further approvers

d. The process was configured to take line-by-line actions on approval

OnLineDeny


a. The approval process instance had at least one line-level stage, although not necessarily either first or last

b. This line is denied, and will not be routed to any more approvers, regardless of the final status of the header or the other lines

OnAllLinesProcessed


a. The last stage of the approval process was a line-level stage

b. All the lines have been either approved or denied

c. If the arguments to this method call are empty arrays, then the process was configured to take line-level actions, and the AWE has already communicated OnLineApprove() and OnLineDeny() events as appropriate for all the lines in this transaction.

d. If the arguments to this method call are not empty arrays, then the process was configured NOT to take line-level actions. This is the first and only intimation to the application of which lines are approved and which lines are denied.

e. This is the last event in the process. The process now ends.

OnTerminate

On receiving this event, developers can be sure that the approval process ended on an explicit call to the process instance to terminate. Usually this means that someone (usually the requester) chose to edit the transaction, and resubmit it for approval. But this is at the application’s discretion: application developers decide when (and if) to terminate a running process.

OnAdhocInsert

This event method is called when an Adhoc is inserted into the Approvals Monitor.



OnAdhocDelete

This event method is called when an Adhoc is deleted from the Approvals Monitor.

A word of caution on the coding of the application’s event handler class. In general, the AWE runs in the context of the component processor, since all approval events happen due to a direct user action on some application page. But in the case of escalations on timeout, this is not true. An application engine process handles escalations, and they can trigger approval event calls. Furthermore, in the future the AWE will support email-only approvals, and Blackberry and cell phone based approvals, which will also be handled outside of any component context.

In all such cases, the arguments to the event methods will contain all the information application developers will need provided they are willing to use SQL objects or SQLExec calls to update their records.

This is why application developers must not make any assumptions about the availability of component records. Also, as noted in the event descriptions above, several events can be called in the context of either the launching component or the approving component, so application developers must not rely, for instance, on OnHeaderApprove being called only in the context of the approval component.

And since a SQLExec call to update the header record to indicate final approval will clash with any attempt on the component processor’s part to update any other field of that record, hence our warning not to allow any component record modifications on the approving component!

Functional Implementation

This section will be most useful to functional business analysts who have to configure approval processes to meet their organization’s needs. End users (i.e., requesters who submit transactions for approval, approvers who decide whether to approve or deny a request, and reviewers) can read the approval workflow sections specific to the particular application with which they are concerned, though, of course, they may find that an understanding of this section provides good insight into how approval processes work.

Business analysts define approval processes to be followed for specific requests (transactions in a particular application). Each application, which uses this approval framework, gets its own unique approval process id—for example, ‘JobOpening’ for Recruiting Solutions Job Openings and ‘JobOffer’ for Recruiting Solutions Job Offers, etc.

Since customers typically need to have different approval processes for different Business Units, each application can have multiple approval processes defined for it, distinguished beyond the approval process id by a Setid value. For instance, the delivered approval workflow for Recruiting Solutions Job Openings uses approval process id ‘JobOpening’, and Setid ‘SHARE’. Different business units can be mapped to different setids, and hence can have different approval processes.

Approval processes (specific to a particular approval process id and setid) are also effective dated, with all the usual PeopleSoft functionality associated with effective dated entities. For instance, if multiple approval processes are active with the approval process id, setid and effective date specification, then the latest active effective dated process is used.

APPROVAL FRAMEWORK ADMINISTRATION COMPONENTS

This section contains an overview of the Administration components used to configure the AWE.



Approval Transaction Registry

Navigation: Set Up HRMS > Common Definitions > Approvals: Approval Transaction Registry

The approval transaction registry is the interface application developers use to register an application with the approval workflow engine. Transactions that require approvals are candidates for being linked to approval workflow engine. You use the Approval Transaction Registry page to link the components, event handler, records, and classes that you created into the approval process for an application transaction, such as a Job Opening or Job Offer. Application developers register the main records and components that make up the transaction.

Approval Process Definition

Navigation: Set Up HRMS > Common Definitions > Approvals: Approval Process

The approval process definition is where the Administrator would design approval workflow for use with an application. This includes setting up routing rules, stages, criteria, steps, recipients, and notifications for each approval process ID. The Administrator would identify the application-supplied transaction definition on which to base approval process definitions. Since businesses typically need to have different approval processes for different business units, each application can have multiple approval processes defined for it, distinguished beyond the approval process ID by a setID value.

User List Definition

Navigation: Set Up HRMS > Common Definitions > Approvals: User List

The Approvals Workflow Framework provides a User-List Definition component to define default lists of approvers. This page is used to define user sources for use with steps in the approval process. When you select a user list source type, you must also select a corresponding value. You can add a new user list or change a current list.

Administration Monitor

Navigation: Set Up HRMS > Common Definitions > Approvals: Administration Monitor

The approval process administrator is a role; users in that role have special privileges concerning approval processes. Such users are queued approval tasks when certain errors occur. Administrators can approve on behalf of others, reassign approval steps from one user to another, etc.

Approver Authorization

Navigation: Set Up HRMS > Common Definitions > Approvals: Approver Authorization

Functionality not fully available in 8.9.



Escalations and Timeouts

Navigation: Set Up HRMS > Common Definitions > Approvals: Escalations and Timeouts

The escalations and timeouts component provides the means to take action on those pending approvals that have met certain criteria, which needs to be escalated.

CONCEPTS

Functional analysts will configure approval workflows in terms of stages, paths, steps, approver user lists, routing criteria, etc. This section describes these concepts in more detail.

Criteria

A criterion is an entity that evaluates to true or false. Criteria are used to determine which steps and paths are to be considered active for a particular request undergoing approval processing. Criteria can be configured by the functional analyst, or can be app classes.

The figure below shows a simple criterion: it evaluates to true if the Job Opening Id in question (Table record HRS_JOB_OPENING, field HRS_JOB_OPENING_ID) is greater than 0. Criterion can be configured based on Field Criteria, Monetary Criteria, and Application Class Criteria.



Figure 29

User Lists

Approvers, reviewers and other actors are grouped by roles and other means. We provide an abstraction across such aggregates, which we call User lists.

In the approval tour above, we had occasion to use two such user lists:

Hiring Manager Posn Supervisor: This user list determined that the Job Opening created by Betty Locherty should route to Jean Parsons.

Recruiter Group: This user list determined that the Job Opening approved by Jean Parsons should route to Douglas Lewis.

The pictures below (Figure 30 and Figure 31) are examples of the user list definition page. User List source can come from four different options (Role, SQL Definition, Query, and Application Class). Figure 32 and Figure 33, show the corresponding code in App Designer for the respective definitions. At the bottom of the User List page there is a section for “Input” options. The checkbox labeled “Include Users as Input” means the AWE will provide the requester (or previous approver) to the user list as “input”. The checkbox labeled “transaction Leys as Input” means the AWE will provide the header keys to the user list as “input”.



Figure 30

Figure 31



Figure 32

Figure 33



Steps

The basic unit of approval. A step has one or more approvers, whose actions are tracked. A step can be configured to require a set number of approvers to act, and has criteria which govern whether or not the step is to be active for the request under consideration.

In the approval tour above, the reader saw a graphical rendition of a step, reproduced below (Figure 34).

Figure 34

A Step starts out in life in the “not routed” state, becomes “pending” when it routes to its approver(s), and—depending upon those approvers’ action(s)—ends life either “approved”, “denied”, or “terminated”. The nuances of all these statuses will be described later in this document.

The step is associated with a single approver, or a pool of approvers. Furthermore, a step can require one or more approvers to approve before it can move on (See Figure 15). A step in which the size of the approver pool just matches the number of approvers who are required to act is called fully constrained. A step that has more approvers than it needs is called under constrained. And finally, a step that has fewer approvers than it needs is called over constrained.

Paths

A path is a sequence of steps. There is no limit on how many steps can be in a path. The picture below (Figure 35) shows a two-step path. Note again that a path is a sequence of steps: step two routes to its approvers only after step one is approved.

Figure 35

It shows the “Hiring Manager Posn Supervisor” Application Class user list in action. Note that the requester of the Job Opening here is by Betty Locherty. The first step above routes to the supervisor Betty Locherty, who is Jean Parsons (HCQAN-HCRUSA is her OprId); the subsequent step routes to the “Recruiter Group”, which in this case is Douglas Lewis.

We expect paths to be a grouping of related approvers; for instance, a single department hierarchy (i.e., manager, director, VP, etc.), or a specialized approval hierarchy for financial audits, commodity requisition approval, etc. In keeping with this expectation, we have made a few design decisions, which will not make sense otherwise, hence it is important to understand this point. Some of these design decisions are:

1. Approver task timeout and escalations settings are at the path level, and apply only to steps within that path.



Figure 36

2. Approvers can pushback only to the start of the path on which they are found. Just like “approve” and “deny”, approvers can also take an action called “pushback”. Pushback means one approver is challenging a previous approver’s decision to approve the request. Pushback routes from one step back to its previous step. Obviously, this is possible only if the step pushing back is not the first step in the path!

Figure 37

3. In evaluating user lists, the approvals workflow engine will supply the user list with the approver in the previous step, if so configured. For a step in a path, this is just the approver(s) in the previous steps. For the first step in a path, though, the previous approver is replaced with the originator of the request.

Stages

There are several situations in which one path (sequence of approval steps) needs to come before another.

In practice, this can pose a User Interface challenge in a browser setting. Browsers and user-friendly graph drawing tools don’t mix well, so we found a simpler means of establishing dependencies between paths. We introduced the concept of stages.

A stage is a collection of paths. Stages come in a single sequence (stage 1, stage 2…). A stage (meaning the paths within the stage) runs when it’s immediately preceding stage finishes. When a stage runs, all the paths within it run simultaneously. The stage is considered complete when all paths within it have finished.

APPROVAL PROCESS CONFIGURATION

Business analysts use a common set of PIA pages to configure these workflows. For example, all the steps in PeopleSoft Recruiting Solutions Job Opening/Job Offer approvals are defined using PeopleSoft pages; so functional users can design and maintain workflow. The next section describes the structure of a configured approval process.

Approval Process Definition

An approval process consists of stages, paths, steps, user lists and criteria. We will now examine in some detail how Recruiting Solutions implemented the Approval Process Definition, for Job Openings. Many of the terms used in the following sections where defined in the section Concepts.



Figure 38

Header Section

Admin Role (administrator role)

Select the user list role used by the approval process to route the transaction to all users filling that role. This is usually based on job function, not individual users. User lists are defined on the User List page. For the Job Opening we used the Role (RS Approval Administrator), which currently is tied to one user (Vickey Adler).

Alert Criteria Click to access the Criteria Definition page where you can define user and field criteria along with monetary and application class criteria for this stage. No Alert Criteria was defined for the Job Opening process.

User Auto Approval

Select to enable the system to remember an approver’s action for this process. The next time this approval process is presented to the approver, the system automatically applies the approver’s selections. The automatic application of steps in the process is left in place until you clear the User Auto Approval check box. User Auto Approval was turned on for the Job Opening process

Stages

Stage Number

Enter the sequence in which you want this stage of the approval acted upon. You can also enter a description for the stage in the Description field.



The Job Opening process has one Stage (Supervisor/Recruiter Grp Aprv)

Each path has an entry criteria associated with it. The purpose of the entry criteria is to determine whether or not that path should “fire” for the particular transaction in question. The Criteria link in the below table, show an example of this for the Job opening process.

Paths

Approval Path

Enter a value that identifies this path. A path is a sequence of steps. An example could be a department path where a requisition requires approval up a department hierarchy. Within a stage, paths execute in parallel with each path inheriting its level from the stage to which it belongs. Path-entry criteria determine whether a path executes for a transaction thread. When a stage becomes active, approvers in the stage get pending work; all its contained paths become active simultaneously. All the paths of a stage queue work to approvers in parallel. The stage is complete only when all paths in it complete. Each path has entry criteria associated with it. The purpose of these criteria is to determine whether or not that path should trigger for a particular transaction. If the system evaluates the criteria you enter for a path to be false for a transaction, then it bypasses the path for that transaction. The Job Opening process contains only one Path. The Supervisor_Recruiter path.

Step Source

Select the method by which steps are instantiated during the approval process. Values are: Static: Select this source to indicate that you want the system to use the individual user-defined steps when it processes an approval. Dynamic: Select this step source to indicate that you want the system to use either a query or an application class when it processes an approval. The Job Opening process uses a Static Step Source.

Path Details

Click to access the Path page where you can define path criteria and escalation parameters, such as whether or not to notify the requester's supervisor. Escalations will also be covered in its own section. Skip Prior Steps for Requester: Again consider the situation in which the originator (requester) of a transaction is also an approver, in a path, which is hierarchical. For example, say you have configured that a Job Opening will need to be approved by managers, then by directors, and finally by vice-presidents. Now consider the situation when a director creates a Job Opening. Whether or not self-approvals are enabled, it clearly makes little sense for the manager-level step to fire. If the “skip-prior” switch on the “Path Details” page is checked (see below), then in this path all approval steps prior to the requester’s step are skipped.

Criteria Click to access the Criteria Definition page where you can define user and field criteria along with monetary and application class criteria for this stage. For the Job Opening process, the Path Criteria is set up for Field Criteria only. The only criterion need to enter this Path is that the HRS_JOB_OPENING.HRS_JOB_OPENING_ID must be greater than Zero. This mean for every Job Opening, which has approvals on, will trigger this Path.



Figure 39

The Job Opening approval process uses a 2-Step process. The first step uses the Direct Reports Data class, which was detailed above in the Concepts section on User Lists. The second step uses the Recruiter Group SQL, which was also detailed above in the Concepts section on User Lists.

Figure 40

Steps

Step Enter the sequence in which you want this step performed during the approval process.

Approver User List

Select the type of approver you want to use for this step. A user list is an entity, which groups users in the system. Roles, queries and application classes are examples of user lists. The system then uses the list and its users to run automated business processes. The list defines the user sources that can be used in approval steps. The Job Opening process uses 2 steps as shown above. The first is the Hiring Manager Posn Supervisor (which uses the Direct Report Data Service) and the second is the Recruiter Group.



Step Details Click to access the Step page where you can define approver requirements, self-approval details, and reviewers. For the Job Opening Step details, use the Step Details link.

Criteria Click to access the Criteria Definition page where you can define user and field criteria along with monetary and application class criteria for this stage. For the Job Opening process, the Step Criteria is set up for Field Criteria only. The only criterion need to enter these steps is that the HRS_JOB_OPENING.HRS_JOB_OPENING_ID must be greater than Zero. This mean for every Job Opening, which has approvals on, will trigger this Step.

Step Details

Approver User List

Select the type of approver you want to use for this step. You use a user list to map users to certain functional roles. The system then uses the list and its users to run automated business processes. The list defines the user sources that can be used in approval steps. This is brought over from the User List field. The Job Opening process uses 2 steps as shown above. The first is the Hiring Manager Posn Supervisor (which uses the Direct Report Data Service) and the second is the Recruiter Group.

Approver Role Name

Select a role that specifies the authority that a user has. The approval workflow engine filters approvers returned by the user list for this role. It also enforces the role at the time the approver acts. If the role assignment changes, such as the approver are no longer in the role, the approver is blocked from acting on the requisition. The Job Opening process does not use an Approver Role name.

All Approvers Required

Select to indicate that all approvers at this step are required to approve the requisition at this step. You can select to have all approvers or some approvers approve the requisition at this step. The Job Opening process only requires one Approver to act on the Step, so this field in not selected.

Some Approvers Required

Select to indicate that it is not required for all approvers to sign off on a requisition. If you select this option, you can define the number of approvers required in the Number of Approvers Needed field. The Job Opening process only requires one Approver to act on the Step.

Number of Approvers Needed

Enter the minimum number of approvers you want to sign off for a requisition at this step. When an approval process is defined and this number is not met, the system notifies the system administrator. As mentioned above the Job Opening only requires one Approver to act on the Step.

Self Approval Select this field to allow Self Approval The Job Opening process does enable the Self Approval functionality.

Self Approval Criteria

Enter criteria to restrict or trigger the self-approval. Since the Job Opening process does enable the Self Approval functionality, no criteria in needed.

Reviewer User List

Select the type of reviewer you want to use for this step. You use a user list to map users to certain functional roles. The system then uses the list and its users to run automated business processes. The list defines the user sources that can be used in approval and review steps. The Job Opening process does not define a Reviewer User List.



Figure 41

APPROVAL NOTIFICATIONS

Although this is part of the Approval Transaction Registry, the Functional Analyst will probably configure it.

Approval notification settings govern which approval events are communicated, to whom they are communicated, and how. The events in question include:

1. The approval process is launched on a transaction

2. An approval step is queued to an approver

3. A review step is queued to a reviewer

4. A thread (line or header) is denied

5. A thread (line or header) is finally approved

6. The approval process is completed

The people to whom such events can be communicated include the requester, the approver(s), and the reviewer(s). The means of communication currently supported are via worklist entries, and e-mail. When using e-mail notifications, the business analyst must create e-mail templates to be used for this purpose.



Notification settings are common to all approval process definitions under the approval process id. (Recall that multiple approval processes can exist under an approval process id, distinguished from each other by Setid and Effective Date fields.) The screenshot below shows the page where this configuration is done.

Header or Line Level Defines whether the notification event is at the header or line level. All events in HCM are at the header level.

Event Select the event for which you want to send a notification. By default values, the approver is always notified of an event and when an error occurs the system notifies the requester and the system administrator. Event values include: Back, Complete, Error, Escalate, Launch, OnApprove, OnDeny, Reactivate, Reassign, Review, Terminate

Menu Name Select the menu name that contains the component you want to register for the Worklist. A menu is a collection of components that contain pages. The menu is the highest level in the hierarchy and you use the menu to access pages.

Approval Component Select the component on which the approval is going to be based. You must also create a URL to send to the requisition approval page for the requisition

SQL Object Identifier (structured query language object identifier)

Select the object identifier you want to use to get content for the email.

Approval Participant Identify the participant that receives the notification. You choices are: Approver, Dynamic, Requester, Administrator, User List, Reviewer

Notification Channel Identify the method of notification. Your choices are: None, Email, Worklist, Both

User List If Participant Type of User List is Selected this is the User List defined.

Template Name Select the template that is used to send the email.

The following can be configured for each event.

Figure 42



Notification Templates

Navigation: PeopleTools > Workflow > Notifications: Generic Templates

The PeopleTools Generic Templates are used to construct the Notification used in the Approval Framework. One important thing to remember is the First template variable must always be the URL.

Figure 43

Figure 44



ESCALATIONS AND TIMEOUTS

As was seen above in Figure 39, we saw the configuration of the Path Details, which included the Escalation Options. Escalations are used to define time elements for when an approver takes too long to approve or deny a pending request.

Escalation and Timeout Settings

Options Select the action to be taken when the approver takes to long to approve or deny a pending request. Values are: Notify: Select to notify the defined user list after the defined days and hours for this approval step have ended. Reassign: Select to reassign the request on to the next approver after the defined days and hours for this approval step have ended.

Hours Enter the number of hours a transaction can remain at on workflow step before being escalated. This field is combined with the Days After Beg field to determine the total time an approver has to take action on an approval request.

Days After Beg

Enter the number of days a transaction can remain at on workflow step before being escalated. This field is combined with the Hours field to determine the total time an approver has to take action on an approval request.

Advance Select this check box to advance the approval process to the next approver.

Reassign To

If the Reassign option is selected from the option dropdown, then a user must be select to reassign to. This is where that is defined.

User List Select a user list to be used to send the escalation notification to, once the escalation is triggered.

Running Escalations and Timeouts

Escalations and Timeouts are run from a run control. For Recruiting this process can only be run by the Approval Administrator that is defined on the Approval Process Definition page. Selecting a Approval Process Id and Setid to run against runs the process.

Figure 45

This user list is tied to the RS Approval Administrator Role. So this mean that if the Escalations are triggered for this process, the notification will be sent to the RS Approval Admin for each Approval Process that met the Escalation Options.

To start the process select Run Select the process and select ok, this will queue the process, which is displayed below.



Figure 46

Figure 47 When the process has run to Complete, the notification will be sent.

Example 1:

Advanced Email (sent when the advance option is triggered):

A Job Opening has been entered which requires your attention.

Job Opening ID: 10120

Posting Title: Specialist-Customer Services

To view this Job Opening, visit:

http://localhost/EMPLOYEE/HRMS/c/MenuName.HRS_HRPM.Component.HRS_JOB_OPENING.GBL?Action=U&HRS_JOB_OPENING_ID=10120

Example 2:

Escalation Notification (sent to the user list when the notify option is triggered):

Escalation Notice:

A Job Opening has been entered which requires your attention.

Job Opening ID: 10120

Posting Title: Specialist-Customer Services

To view this Job Opening, visit:

http://localhost/EMPLOYEE/HRMS/c/MenuName.HRS_HRPM.Component.HRS_JOB_OPENING.GBL?Action=U&HRS_JOB_OPENING_ID=10120

http://localhost/EMPLOYEE/HRMS/c/MenuName.HRS_HRPM.Component.HRS_JOB_OPENING.GBL?Action=U

http://localhost/EMPLOYEE/HRMS/c/MenuName.HRS_HRPM.Component.HRS_JOB_OPENING.GBL?Action=U



Administration Monitor:

From the Administration monitor, we can see comment that has been system generated to show that the escalations have been executed.

If last Approver:

Figure 48

If another Approver is in the chain:

Figure 49

SMTP & URL Configuration

For events that send email, the Process Scheduler properties file must be updated. This is located in C:\<PTOOLS_HOME>\appserv\prcs\<APPSERVER>\psprcs.cfg.

Edit this file and search for SMTP. Edit the following settings:

[SMTP Settings]

;=========================================================================

; Settings for SMTP mail

; All controls under SMTP Settings can be dynamically changed

;=========================================================================

; Dynamic change allowed for SMTPServer

SMTPServer=psp-smtp-01

; Dynamic change allowed for SMTPPort

SMTPPort=25

; Dynamic change allowed for SMTPServer1



SMTPServer1=

; Dynamic change allowed for SMTPPort1

SMTPPort1=0

; Dynamic change allowed for SMTPSender

[email protected]

; Dynamic change allowed for SMTPSourceMachine

SMTPSourceMachine=%PS_MACH%.peoplesoft.com

; Dynamic change allowed for SMTPCharacterSet

SMTPCharacterSet=UTF-8

; Dynamic change allowed for SMTPEncodingDLL

SMTPEncodingDLL=

SMTPTrace=0

SMTPSendTime=0

For “Receipt Notification”, users receive an email with a link back to a PIA page. The name of the web server machine must be configured in the following location:

• Navigate to: PeopleTools > Utilities > URL’s

• Search for “EMP_SERVLET”. If this value does not exist, add it.

• Enter the machine and port name in the URL field and include a trailing slash.

Eg. http://drk070102:8400/

• Click Save.

ADMINISTRATION MONITOR

The approval process administrator is a role; users in that role have special privileges concerning approval processes. Such users are queued approval tasks when certain errors occur. Administrators can approve on behalf of others, reassign approval steps from one user to another, etc.

From the Search page, the Administrator can enter search criteria to return that Approval Process they want. With in that search result they can also filter based on the Level Record Key values defined in the Transaction Registry.

http://drk070102:8400/



Figure 50

Once the search is complete they can enter the Administration Monitor. From this page the Administrator can take many actions. The Administrator can Approve or Deny on behalf of, Reassign to another Approver, Insert Adhoc’s, or just view the status of the pending process.



Figure 51

Object Drill Down

Integration points for approvals in the Recruiting Solutions system.



Figure 52

API’S (APPLICATION CLASSES, CI’S, VIEWS)

Important – You must ONLY access the SCM Approval Framework using the HCM interfaces described below. If they do not meet your needs please contact the HCM Common Components team and negotiate an enhancement. Do not change these objects – they are a common component used by other groups.

HCM Common Components built and maintains a thin wrapper that encapsulates the SCM Approval Framework. This is done to prevent any direct calls to the framework’s objects. We avoid this to make transition to a different framework in the future less invasive.



Package Diagram (HMAF_AWE)

Figure 53

Common Application Classes:

Application Package Application Class Description

HMAF_AWE ApprovalsFactroy The interfaces will be returned to the Applications developer through the use of a Factory Class. The Factory Class will encapsulate the logic to decide which subclass to instantiate.

HMAF_AWE IapprovalManager Interface for the ApprovalManager class.

HMAF_AWE IlaunchManager Interface for the LaunchManager class.

HMAF_AWE IstatusMonitor Interface for the StatusMonitor class.

HMAF_AWE ApprovalEventHandler Wrapper for AWE ApprovalEventHandler, each Application extends this class, with Application specific logic. Used in the Transaction Registry, for Event Handling.

HMAF_AWE ApprovalManager

Wrapper for AWE ApprovalManager; The approval manager object is app developers' interface to the Approvals Workflow Engine (AWE). Most developers will not find it necessary to directly access any other AWE objects.




Application developers should instantiate this class as a component-scoped variable. (Note: Using the ApprovalsFactory class, getApprovalManager method). The best place to initialize this class is in the component post-build event. The class can be instantiated with information readily available to developers at component post-build time.

Developers should examine the Boolean-valued properties of this object to know whether or not the user entering the approval component has any pending approvals work. If so, the GetPending () method will tell them exactly what is pending, and the methods DoApprove (), DoDeny (), etc. will enable them to implement the full approval functionality.

HMAF_AWE LaunchManager

Wrapper for AWE LaunchManager; Application developers should instantiate this class as a component-scoped variable. The best place to initialize this class is in the component post-build event. The constructor takes all the information needed to fully initialize this object. An object of this class has several Boolean-valued properties, which will prove useful to app developers in tailoring their pages to suit the situation. For instance, when an object of this class is initialized with a brand new app transaction record, the AWE will not find any approval processes for it. The property submitEnabled will then be true, and the application page may then display a "submit" button. They will, of course, have to write code to interpret a click of that button to trigger a call to this object's DoSubmit() method.

HMAF_AWE StatusMonitor Wrapper for AWE awStatusMonitor. Used to build and display the Approval Chain display area.

Recruiting Solutions Module Specific Classes


HRS_AWE_EVNT_HNDLR JobOfferHandler Handles the overrides of the AWE Event handler for the Job Offer

HRS_AWE_EVNT_HNDLR HRS_JOB_OFFER.ThreadDescr Used to override the Approval Monitor descriptions for the Job Offer

HRS_AWE_EVNT_HNDLR JobOpeningHandler Handles the overrides of the AWE Event handler for the Job Opening

HRS_AWE_EVNT_HNDLR HRS_JOB_OPENING.ThreadDescr Used to override the Approval Monitor descriptions for the Job Offer



Recruiting Solutions API Views

Name Description

HRS_DIAG_JO_VW RS Diagnostic view, used by the diagnostic utility for Job Openings

HRS_DIAG_OFF_VW RS Diagnostic view, used by the diagnostic utility for Job Offers

HRS_JO_PEND_APP Job Opening Pending Approvals, used by the Pending Approval Component

HRS_OFF_PND_APP Offer Pending Approvals, used by the Pending Approval Component

HRS_STEPINST_I Approval Step Interface

rp hcmrs approvals framework1

Documents