Sei sulla pagina 1di 59

PeopleSoft Red Paper Series

Recruiting Solutions 8.9 Approvals


Framework
By: Donald Knapp
April 2005
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.

.
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

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
Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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. 5


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 6


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

You can create Application Packages in PeopleSoft


Application Designer. These packages contain application
classes (and may contain other packages also). An application
Application Packages 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.

PeopleSoft Application Designer is an integrated development


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

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,
Data Mover 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.

© Copyright Oracle Corporation 2005. All rights reserved. 7


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005 All rights reserved. 8


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 9


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Figure 3

Select the Approvals hyperlink to access the Approval Process Monitor.

Figure 4

© Copyright Oracle Corporation 2005 All rights reserved. 10


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 11


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005 All rights reserved. 12


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 13


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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).

© Copyright Oracle Corporation 2005 All rights reserved. 14


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 15


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 16


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.
© Copyright Oracle Corporation 2005. All rights reserved. 17
Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 18


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 19


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 20


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 21


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 Select the table from which you want to extract personal contact information for the approver.
(approval user information This is the information that appears when you use the approval status monitor to display
view) 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

© Copyright Oracle Corporation 2005 All rights reserved. 22


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 Select the component on which the approval is going to be based. You must also create a URL to send to the
Component job opening or job offer approval page for the job opening.

Approval Event Handler Class

Root Package Select the parent application class through which events are exposed. This defines the action to take based
ID 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 Select a thread description that will be used to identify the description that is used for the status
description) 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.

© Copyright Oracle Corporation 2005. All rights reserved. 23


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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:

© Copyright Oracle Corporation 2005 All rights reserved. 24


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 25


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 26


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 27


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005 All rights reserved. 28


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 29


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 30


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 31


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 32


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

On receiving this event, developers can be sure that

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.

© Copyright Oracle Corporation 2005. All rights reserved. 33


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

OnLineApprove

On receiving this event, developers can be sure that

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

On receiving this event, developers can be sure that

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

On receiving this event, developers can be sure that

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.

© Copyright Oracle Corporation 2005 All rights reserved. 34


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 35


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 36


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 37


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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”.

© Copyright Oracle Corporation 2005 All rights reserved. 38


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Figure 30

Figure 31

© Copyright Oracle Corporation 2005. All rights reserved. 39


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Figure 32

Figure 33

© Copyright Oracle Corporation 2005 All rights reserved. 40


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 41


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 42


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Figure 38

Header Section
Admin Role Select the user list role used by the approval process to route the transaction to all users filling that role. This is usually
(administrator role) 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 Select to enable the system to remember an approver’s action for this process. The next time this approval process is
Approval 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 Enter the sequence in which you want this stage of the approval acted upon. You can also enter a description for the stage in
Number the Description field.

© Copyright Oracle Corporation 2005. All rights reserved. 43


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 Enter a value that identifies this path. A path is a sequence of steps. An example could be a department path where a requisition
Path 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 Select the method by which steps are instantiated during the approval process. Values are:
Source 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 Click to access the Path page where you can define path criteria and escalation parameters, such as whether or not to notify the
Details 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.

© Copyright Oracle Corporation 2005 All rights reserved. 44


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 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,
User List 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.

© Copyright Oracle Corporation 2005. All rights reserved. 45


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 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
List 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 Select a role that specifies the authority that a user has. The approval workflow engine filters approvers returned by the
Name 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 Select to indicate that all approvers at this step are required to approve the requisition at this step. You can select to have
Required 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 Select to indicate that it is not required for all approvers to sign off on a requisition. If you select this option, you can
Required 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 Enter the minimum number of approvers you want to sign off for a requisition at this step. When an approval process is
Approvers defined and this number is not met, the system notifies the system administrator.
Needed

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 Enter criteria to restrict or trigger the self-approval.
Criteria

Since the Job Opening process does enable the Self Approval functionality, no criteria in needed.
Reviewer User 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
List 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.

© Copyright Oracle Corporation 2005 All rights reserved. 46


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005. All rights reserved. 47


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 Select the object identifier you want to use to get content for the email.
query language object identifier)
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

© Copyright Oracle Corporation 2005 All rights reserved. 48


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 49


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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 Enter the number of days a transaction can remain at on workflow step before being escalated. This field is
Beg 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 If the Reassign option is selected from the option dropdown, then a user must be select to reassign to. This is
To 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.

© Copyright Oracle Corporation 2005 All rights reserved. 50


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 51


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005 All rights reserved. 52


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

SMTPServer1=

; Dynamic change allowed for SMTPPort1

SMTPPort1=0

; Dynamic change allowed for SMTPSender

SMTPSender=PeopleSoft@peoplesoft.com

; 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.

© Copyright Oracle Corporation 2005. All rights reserved. 53


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 54


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Figure 51

Object Drill Down

Integration points for approvals in the Recruiting Solutions system.

© Copyright Oracle Corporation 2005. All rights reserved. 55


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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.

© Copyright Oracle Corporation 2005 All rights reserved. 56


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Package Diagram (HMAF_AWE)

Figure 53

Common Application Classes:

Application
Application Class Description
Package

The interfaces will be returned to the Applications developer


HMAF_AWE ApprovalsFactroy 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.

Wrapper for AWE ApprovalEventHandler, each Application


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

Wrapper for AWE ApprovalManager; The approval manager


object is app developers' interface to the Approvals Workflow
HMAF_AWE ApprovalManager
Engine (AWE). Most developers will not find it necessary to
directly access any other AWE objects.

© Copyright Oracle Corporation 2005. All rights reserved. 57


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

Application
Application Class Description
Package

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.

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
HMAF_AWE LaunchManager 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.

Wrapper for AWE awStatusMonitor. Used to build and display


HMAF_AWE StatusMonitor
the Approval Chain display area.

Recruiting Solutions Module Specific Classes

Application Package Application Class Description


Handles the overrides of the AWE Event
HRS_AWE_EVNT_HNDLR JobOfferHandler
handler for the Job Offer
Used to override the Approval Monitor
HRS_AWE_EVNT_HNDLR HRS_JOB_OFFER.ThreadDescr
descriptions for the Job Offer

Handles the overrides of the AWE Event


HRS_AWE_EVNT_HNDLR JobOpeningHandler
handler for the Job Opening

Used to override the Approval Monitor


HRS_AWE_EVNT_HNDLR HRS_JOB_OPENING.ThreadDescr
descriptions for the Job Offer

© Copyright Oracle Corporation 2005 All rights reserved. 58


Recruiting Solutions 8.9 Approvals Framework 6/20/2005

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

© Copyright Oracle Corporation 2005. All rights reserved. 59