You are on page 1of 60

PeopleSoft Red Paper Series

Approval Workflow Engine (AWE) for


HCM 9.0
By: Vincent Pallari, Renli Wang & Robbin Velayedam
HCM Shared Components Team
February 2007February 2007

INCLUDING:
Understanding the Approval Workflow Engine AWE
Defining Support Objects for implementing AWE
Registering self-service transactions to use AWE
Approval Workflow Engine (AWE) for HCM 9.0

Copyright 2007 PeopleSoft, Inc. All rights reserved.


Printed on Recycled Paper. Printed in the United States of America.

Restricted Rights

The information contained in this document is proprietary and confidential to PeopleSoft, Inc.

Comments on this document can be submitted to redpaper@peoplesoft.com. We encourage you


provide feedback on this Red Paper and will ensure that it is updated based on feedback
received. When you send information to PeopleSoft, you grant PeopleSoft a non-exclusive
right to use or distribute the information in any way it believes appropriate without incurring
any obligation to you.

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 PeopleSoft, Inc.

This document is subject to change without notice, and PeopleSoft does not warrant that the
material contained in this document is error-free. If you find any problems with this document,
please report them to PeopleSoft in writing.

This material has not been submitted to any formal PeopleSoft test and is published AS IS. It
has not been the subject of rigorous review. PeopleSoft assumes no responsibility for its
accuracy or completeness. The use of this information or the implementation of any of these
techniques is a customer responsibility and depends on the customer's ability to evaluate and
integrate them into the customer's operational environment. While PeopleSoft may have
reviewed each item for accuracy in a specific situation, there is no guarantee that the same or
similar results will be obtained elsewhere. Customers attempting to adapt these techniques to
their own environments do so at their own risk
Information in this book was developed in conjunction with use of the product specified, and is
limited in application to those specific hardware and software products and levels.

PeopleSoft may have patents or pending patent applications covering subject matter in this
document. The furnishing of this document does not give you any license to these patents

Any pointers in this publication to external Web sites are provided for convenience only and do
not in any manner serve as an endorsement of these Web sites.

PeopleSoft, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, PeopleTalk, and Vantive are


registered trademarks, and Pure Internet Architecture, Intelligent Context Manager, and The
Real-Time Enterprise are trademarks of PeopleSoft, Inc. All other company and product names
may be trademarks of their respective owners. The information contained herein is subject to
change without notice.
Table of Contents

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

CHAPTER 1 - INTRODUCTION ..................................................................................................................................... 4


Structure of this Red Paper 4
Related Materials 4

CHAPTER 2 - DEFINING SUPPORT OBJECTS FOR AWE...................................................................................... 5


Introduction .............................................................................................................................................................................. 5
Header Record.......................................................................................................................................................................... 6
Cross Reference Record ........................................................................................................................................................... 7
PTAFAW_IDS......................................................................................................................................................................... 8
Event Handler........................................................................................................................................................................... 9
Adhoc Access Class ............................................................................................................................................................... 10
Thread Class........................................................................................................................................................................... 11
Email Approvals Form Generator Class................................................................................................................................. 13
Approval User Info View ....................................................................................................................................................... 13
Email Template(s) .................................................................................................................................................................. 15
Email Template SQL Object(s) .............................................................................................................................................. 16
User Lists Definitions (Maintain User Lists).......................................................................................................................... 17

CHAPTER 3 - REGISTERING TRANSACTIONS IN AWE...................................................................................... 19


Register Transactions ............................................................................................................................................................. 20
Workflow Transactions .......................................................................................................................................................... 23
Configure Transactions .......................................................................................................................................................... 24
Setup Process Definitions....................................................................................................................................................... 31
Criteria Definitions................................................................................................................................................................. 37
Implementing the Status Monitor ........................................................................................................................................... 41
Application PeopleCode......................................................................................................................................................... 42
Security .................................................................................................................................................................................. 44
Appendix A. HCM Approval Workflow Engine Factory Package........................................................................................ 46
Appendix B. AWE Base Classes........................................................................................................................................... 47

FREQUENTLY ASKED QUESTIONS .......................................................................................................................... 53

REVISION HISTORY...................................................................................................................................................... 60
Authors................................................................................................................................................................................... 60
Reviewers ............................................................................................................................................................................... 60
Revision History..................................................................................................................................................................... 60

3
Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Chapter 1 - Introduction

This Red Paper is a practical guide for technical users, functional analysts, installers, system administrators, and developers
who implement, maintain, or develop applications for your PeopleSoft system. This Red Paper discusses how to implement and
set up the Approval Workflow Engine (AWE), including how to define all the required support objects.

STRUCTURE OF THIS RED PAPER


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 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 PeopleTools or the HCM applications. We
recommend you first read the Approvals related information in the PeopleTools and Applications PeopleBooks to ensure that
you have a well-rounded understanding of the technology.

Many of the fundamental concepts related to AWE are discussed in the following PeopleSoft PeopleBooks:
PeopleSoft Enterprise HRMS 9.0 Application Fundamentals PeopleBook, “Setting Up and Working with Approvals”
PeopleSoft Enterprise Absence Management 9.0 PeopleBook, “Using Approvals with Absence Management”
PeopleSoft Enterprise Global Payroll 9.0 PeopleBook, “Using Approvals with Absence Management”
PeopleSoft Enterprise Human Resources 9.0 PeopleBook: Manage Profiles, “Managing Profiles,” Approving Profile Changes
PeopleSoft Enterprise Talent Acquisition Manager 9.0 PeopleBook, “Setting Up Recruiting Processes,” Setting Up Talent
Acquisition Manager Implementation Defaults
PeopleSoft Enterprise eProfile Manager Desktop 9.0 PeopleBook, “Managing Direct Reports,” Understanding the Management
of Direct Reports
PeopleSoft Enterprise HRMS 9.0 Application Fundamentals PeopleBook, "Setting Up and Working with Delegation"

© Copyright PeopleSoft Corporation 2007. All rights reserved. 4


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Chapter 2 - Defining Support Objects for AWE

Introduction
The HCM Approval Workflow Engine (AWE) is the current HCM standard for transactions requiring approvals processing.
This red paper will describe the step-by-step process for registering an HCM transaction in the AWE. It is important to note
that this red paper will focus only on the HCM 9.0 release of the AWE. Please read this document in its entirety first so that
you get a complete understanding of how all the pieces fit together. This red paper assumes that you have read and understand
the terminology presented in the PeopleSoft Enterprise HRMS 9.0 Application Fundamentals PeopleBook, “Setting Up and
Working with Approvals”
The Approval Workflow Engine (AWE) is the engine that provides the framework and capabilities for creating, running, and
managing approval processes. The engine uses a series of database objects combined with application component configuration
settings to determine how to process approvals using workflow.
Approval workflows are triggered when requesters submit a transaction, such as a promotion. The application hands the
transaction over to the Approval Workflow Engine, which finds the appropriate approval process definition and launches the
approval workflow. A set of approvers then carries out tasks related to the transaction.
The Approval Workflow Engine enables three levels of users to develop, configure, and use transaction approvals that meet
their organizational requirements. For example, the process of submitting a promotion and getting it approved requires defining
who will approve the promotion, the order in which they will approve it, and how it will be routed to approvers.
In contrast to the standard PeopleSoft workflow, which requires advanced technical skills in PeopleSoft PeopleTools to create
and maintain, approval workflow provides an alternative workflow that is much easier to create, configure, and maintain. For
example, all of the steps in approval workflow are defined using PeopleSoft pages rather than underlying PeopleSoft
PeopleCode, so functional users can design and maintain workflow using these online PeopleSoft pages instead of requiring
technical developers to create workflow rules.

Not all applications within PeopleSoft HCM are delivered in v. 9.0 using the new AWE for processing approvals. Some
applications decided to retain the legacy approval framework to process their transactions. The following HCM applications
have adopted the AWE to process approvals in v. 9.0: eProfile, eProfile Manager, Job Profile Manager, Absence Management,
Recruiting, ELM, and ePerformance. For the best illustration of which specific transactions use AWE for approvals and which
use legacy approval workflow, please see the section on Workflow Transactions. Beyond these adopting applications, you may
choose to register your own transactions or other delivered PeopleSoft HCM applications with the AWE by following the
guidelines described in this red paper.

The AWE was originally introduced in an 8.x release of the PeopleSoft’s Supply Chain Management (SCM) application. Many
of SCM’s requirements for approvals are far beyond what HCM’s typical requirements would be for approvals. With v. 9.0 we
refined the AWE to work in conjunction with HCM specific use cases but you will undoubtedly encounter some functionality --
by way of the approval setup pages -- that are not appropriate for HCM transactions. To avoid spending time on functionality
that you probably will not use, follow the steps outlined in this red paper, which are specific to implementing HCM
transactions.

The majority of the code supporting the AWE is delivered as part of PeopleTools 8.48. The HCM Shared Components team
has also delivered code to help implement AWE in the HCM application database. The developers of the adopting applications
listed above registered their transactions and customized their approval pages to leverage the AWE as delivered. That is why it
is important to also review the PeopleBooks for each application using the AWE to learn about the specific modifications they
may have made.

This red paper is divided into two main chapters. The first chapter illustrates how to define all the technical support objects
required for setting up and using the AWE. These support objects must be handled by a technical resource well versed in
PeopleTools technology and applications implementation. The second chapter focuses on how to register transactions and set
up process definitions in AWE for approval processing. This is largely a technical effort, however a functional analyst who
knows the business process of approvals for your organization should be consulted.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 5


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Here is a brief summary of the tasks detailed in this paper and what tool you will need to complete them.
Task Tool
Header Record PeopleTools Application Designer
Cross Reference Record PeopleTools Application Designer
PTAFAW_IDS PeopleSoft Database
Event Handler PeopleTools Application Designer
Adhoc Access Class PeopleTools Application Designer
Thread Class PeopleTools Application Designer
Email Approvals Form Generator Class AWE Application Setup
Approval User Info View PeopleTools Application Designer
Email Template AWE Application or PeopleTools Setup
Email Template SQL Objects PeopleTools Application Designer
User Lists Definition AWE Application Setup
Approval Transaction Registry AWE Application Setup
Workflow Transactions AWE Application Setup
Transaction Configuration AWE Application Setup
Criteria Definitions AWE Application Setup
Approval Process Definitions AWE Application Setup
Application PeopleCode PeopleTools Application Designer
Security PeopleTools Setup

The sample data shown in the screenshots to follow are for a dummy Expense Report and is not a delivered application.
The objects shown do not exist in the delivered v. 9.0 HCM database. The objects shown are for illustrative purposes only.

Header Record

One of the few transaction side requirements of the AWE is the Header Record. The Header Record should be the highest-level
transaction record having a 1-to-1 relationship with the transaction. In other words, each transaction that is submitted should
have only one row in the Header Record. All of the delivered processes in HCM are using Header level approvals. The Expense
Reporting application might have a record (EXP_RPT_HDR) that contains information about each transaction as well as a
record (EXP_RPT_DTL) that contains information about each line item.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 6


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

In the following example, EXP_RPT_HDR would be your header record.

Transaction_NBR is the only Key in the record shown above.

Cross Reference Record

Another requirement for each adopting applications is the Cross Reference record. The cross-reference record is simply a
record containing the delivered PTAFAW_XREF_SBR as well as all the key fields from the applications header record
MARKED AS NON-KEY fields. For example, using the EXP_RPT_HDR record:

© Copyright PeopleSoft Corporation 2007. All rights reserved. 7


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Unlike the header record, which plays a part in your transaction processing, the cross-reference record is used solely by the
AWE. Your application does not need to retrieve any information off this record and should never update this record. The
AWE uses this record as its only link between itself and the transaction.

In the event that your transaction is designed to support line-level approvals, then your cross-reference record would be
constructed using the key fields from your line-level record. Using the expense-reporting example, the keys from
EXP_RPT_DTL would be used and the field LINEID would be added to the cross-reference record as a NON-key field.

PTAFAW_IDS

The PTAFAW_IDS record is the seed record that is used to create some of AWE’s key values. For example, your cross-
reference record contains a numeric field called PTAFTHREAD_ID. Whenever this value is set for a newly instantiated
transaction, the engine refers to the PTAFAW_IDS.PTAFAWCOUNTER field. The engine retrieves the value, and then
increments it accordingly for the next transaction.

It is up to you to:
1) Insert a row into PTAFAW_IDS manually while setting:

a. PTAFCOUNTERNAME = to the name of your cross reference record

b. PTAFAWCOUNTER = any number you wish to use as the initial seed (i.e. 1, or 10 or 222, or 1100), its up to
you

Keep in mind that once this value is set and a transaction is submitted, the seed value must not be changed manually. This can
cause multiple transactions to end up with the same keys. For example, if you set the seed to 100, submit a transaction, change
the seed back 100 and submit again, the 2 submitted transactions would have the same PTAFTHREAD_ID. This will cause
problems.

If the transaction implementing the AWE for release 9.0 has delivered demo data in the core engine tables, then changing the
seed should be avoided unless new demo data is planned.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 8


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Event Handler

The AWE is designed around a series of specific, pre-defined events. The engine then leverages PeopleSoft Application
Classes in order to allow applications to extend its own processing. This allows the adopting application to assign specific
pieces of PeopleCode to be fired during these events. Here is an example of what an event handler package and class
definition should look like:

Package Definition:

Class Definition:
class expRpt_EvtHndlr extends HMAF_AWE:Wrapper:ApprovalEventHandler;
method expRpt_EvtHndlr();
method OnProcessLaunch(&appInst As PTAF_CORE:ENGINE:AppInst);
method OnStepActivate(&stepinst As PTAF_CORE:ENGINE:StepInst);
method OnStepHold(&userinst As PTAF_CORE:ENGINE:UserStepInst);
method OnStepReassign(&userinst As PTAF_CORE:ENGINE:UserStepInst, &origApprover As string);
method OnStepComplete(&stepinst As PTAF_CORE:ENGINE:StepInst);
method OnStepPushback(&userinst As PTAF_CORE:ENGINE:UserStepInst);
method OnStepReactivate(&stepinst As PTAF_CORE:ENGINE:StepInst);
method OnFinalHeaderDeny(&appinst As PTAF_CORE:ENGINE:AppInst);
method OnHeaderDeny(&userinst As PTAF_CORE:ENGINE:UserStepInst);
method OnHeaderApprove(&appinst As PTAF_CORE:ENGINE:AppInst);
method OnLineDeny(&userstep As PTAF_CORE:ENGINE:UserStepInst);
method OnLineApprove(&appinst As PTAF_CORE:ENGINE:AppInst, &thread As PTAF_CORE:ENGINE:Thread);
method OnAllLinesProcessed(&appinst As PTAF_CORE:ENGINE:AppInst, &approved As array of
PTAF_CORE:ENGINE:Thread, &denied As array of PTAF_CORE:ENGINE:Thread);
method OnTerminate(&appinst As PTAF_CORE:ENGINE:AppInst);
method OnError(&stepinst As PTAF_CORE:ENGINE:StepInst);
method OnStepReview(&stepinst As PTAF_CORE:ENGINE:StepInst, &reviewers As array of string);
method OnTimeout(&userinst As PTAF_CORE:ENGINE:UserStepInst, &notify As string);
method OnAdHocInsert(&stepinst As PTAF_CORE:ENGINE:AdHocStepInst, &approver As array of string);
method OnAdHocDelete(&stepinst As PTAF_CORE:ENGINE:AdHocStepInst);
method OnUserLocked(&userinst As PTAF_CORE:ENGINE:UserStepInst);
method ProcessNotifications(&appinst As PTAF_CORE:ENGINE:AppInst);

You will be required to create your own version of this class. When you extend the superclass, make sure that your SUB class
only contains the methods that you want to extend.

Within each method (which corresponds to a single event) you can write whatever code you feel necessary to modify the
transaction. For example, your header record may have a field that tracks the overall status of the transaction (STATUS field).
Therefore, the extended Method OnHeaderDeny() might have code to set that field value to “D” when the transaction is denied.
Example:
Method OnHeaderDeny
&MyHdrRec = CreateRecord(Record.EXP_RPT_HDR)
&MyHdrRec.TRANSACTION_NBR.Value = &TransNum

© Copyright PeopleSoft Corporation 2007. All rights reserved. 9


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

&MyHdrRec.SelectByKeys()
&MyHdrRec.Status.Value = “D”
&MyHdrRec.Update()
End-Method

Likewise, if the transaction is approved, the onHeaderApprove method might look like this:

Method OnHeaderApprove
&MyHdrRec = CreateRecord(Record.EXP_RPT_HDR)
&MyHdrRec.TRANSACTION_NBR.Value = &TransNum
&MyHdrRec.SelectByKeys()
&MyHdrRec.Status.Value = “A”
&MyHdrRec.Update()
End-Method

It is also important to note that each applications event handler class must extend the
HMAF_AWE:Wrapper:ApprovalEventHandler class. Once this class is extended, the application event handler sub-class
should only include the methods (or properties) that it wishes to overwrite. For example, if the subclass does not have any
application specific code for the OnProcessLaunch event, then the OnProcessLaunch method should not be included in the
sub-class. Also, each method in the sub-class that does overwrite the super class should include a call to the super class
FIRST. This will allow your code’s super class logic to fire first, then the sub class code. For example, the
onHeaderApprove event might look like this:

Method OnHeaderApprove
%Super.OnHeaderApprover(&appinst);
&MyHdrRec = CreateRecord(Record.EXP_RPT_HDR)
&MyHdrRec.TRANSACTION_NBR.Value = &TransNum
&MyHdrRec.SelectByKeys()
&MyHdrRec.Status.Value = “A”
&MyHdrRec.Update()
End-Method

Adhoc Access Class

Like the Event Handler, the Adhoc Access class allows each application to extend the core AWE logic. By creating an Adhoc
access class, you can control when a user is allowed to modify the approval path and participants. Here is an example of what
an Adhoc Access package and class definition should look like:

Package Definition

Class Definition:
class adHocAccess extends PTAF_MONITOR:ADHOC_OBJECTS:adhocAccessLogicBase
method adhocAccess ();

© Copyright PeopleSoft Corporation 2001. All rights reserved. 10


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

method allowInsert(&oprid As string, &stepBefore As PTAF_CORE:ENGINE:StepInst, &stepAfter As


PTAF_CORE:ENGINE:StepInst) Returns boolean;
method allowDelete(&oprid As string, &currentStep As PTAF_CORE:ENGINE:StepInst) Returns boolean;
method allowNewPath(&oprid As string, &stage As PTAF_CORE:ENGINE:StageInst) Returns boolean;
end-class;

Here is an example of how one might extend the adHocAccess class allowInsert method:

Method allowInsert
If IsUserInRole(“ExpensesAdministrator”) then
Return True
Else
Return False
End-if;
End-method;

AdHoc Class and Status Monitor 'mode' parameter work in conjunction with each other. If the parameter D (Display only) is
passed into the status monitor at runtime, then the AdHoc Class is ignored. If the parameter A (AdHoc) is passed in, then
AdHoc class is used. So basically, if D is used, then no one ever interacts using AdHoc. However, If A is passed in then the
AWE uses the AdHoc class to further determine if that particular user can use AdHoc.

Thread Class

The Thread Class relates to what is displayed on the Status Monitor. The Status Monitor, as shown below, illustrates the
approval process flow and up to date status of the process. Information on how to implement Status Monitor in your
application, refer to the Implementing the Status Monitor.

When constructing the status monitor, the AWE uses the Thread keys as the default group box header. The threadDescr class
allows you to override this default and display something more meaningful to the user. Also, for each step within an approval
process, the administrator monitor generates a link for viewing additional information related to that user. The default link text
is constructed using the description of the users operator id. If an adopting application wishes to override that functionality, the
can do so by extending the getUserName method in the threadDescr base class. Here is an example of what a threadDescr class
might look like:

Package Definition:

© Copyright PeopleSoft Corporation 2007. All rights reserved. 11


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Class Definition:
Class threadDescr extends PTAF_MONITOR:MONITOR:threadDescrBase
method threadDescr();
method getThreadDescr(&keys As array of Field) Returns string;
method getWorklistDescr(&recApplication As Record) Returns string;
method getUserName(&OprId as String) Returns string
end-class;

Here is an example of how one might extend the threadDescrBase class getThreadDescr method to return the name of the
person and the date of the transaction to be used as the Status Monitor header:

Method getThreadDescr
/*Create Header Record*/
&MyHdrRec = CreateRecord(Record.EXP_RPT_HDR)
/*Loop through array of keys*/
for &I = 1 to &keys.Len
/*For each field and field value*/
&FieldName = &keys[&I].Name
&FieldValue = & keys[&I].Value
/*Loop through header record matching field names and setting appropriate values*/
For &j = 1 to &MyHdrRec.FieldCount
If &MyHeaderRec.GetField(&j).Name = &keys[&I].name then
&MyHeaderRec.GetField(&j).Value = &keys[&I].value
end-if;
end-for;
end-for;
/*Select Row From Header Record*/
&MyHdrRec.SelectByKeys()
Return Get_Person_name(&MyHdrRec.Emplid.Value) | “ “ | &MyHdrRec.Trans_Dt.Value;
End-method;

method getUserName
/+ &oprid as String +/
/+ Returns String +/
/+ Extends/implements PTAF_MONITOR:MONITOR:threadDescrBase.getUserName +/
Local HCSC_THREAD_DESCR:hcscThreadDescr &TDClass;
&TDClass = create HCSC_THREAD_DESCR:hcscThreadDescr();
Return &TDClass.getUserName(&oprid);
end-method;

The Shared Components team delivered a threadDescr utility class that you can leverage for extending getUserName. The
application Class HCSC_THREAD_DESCR:hcscThreadDescr has method called getUserName. This method performs the
following operation:

1. Select EMPLID from PSOPRDEFN where OPRID = OperId Parm Passed In

© Copyright PeopleSoft Corporation 2001. All rights reserved. 12


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

2. Select NAME from PS_PERSON_NAME where EMPLID = Emplid Retrieved from PSOPRDEFN
3. If all (Name) return Name
4. Else If none (NAME) then look for PSOPRDEFN Descr associated with OperId Parm
5. If all (Descr) then return Descr
6. Else Return Oprid Parm

To use the delivered threadDescr class, you must use the Thread Package as shown below. For more information, see the
Register Transactions section in Chapter 3.

Email Approvals Form Generator Class

If you wish to allow users to approve transactions straight from the email notification that they receive via the Email
Collaboration Framework (internal to Oracle click here; external to Oracle click here), they will have to create an Email
Approvals Form Generator Class. Here is an example of what an Email Approvals Form Generator Class might look like:

Package Definition:
Class Definition:
class formGenerator extends PTAF_EMC:API: formGeneratorBase
method formGeneratorBase(&threads As array of PTAF_CORE:ENGINE:Thread, &userID As string);
method returnEFM() Returns PTAF_EMC:API:emailFormManager;
end-class;

Again, please refer to the Email Collaboration Framework implementation guide for how to construct your returnEFM()
method.

Approval User Info View

The approval user info view is a view that is used to display additional information about AWE Participants. When an
individual user is displayed as being a participant of an approval process in the Approval Status Monitor, only his/her operator
ID is displayed. By defining an Approval User Info View, when a user selects the Operator ID of a participant in the system,
the AWE will display the additional information that you have defined in your view on the Approver Additional Information
page. For example:

Approval User Info View Definition:

In this example, our view selects OPRID (required for all Approval User Info Views), Empld, Last Name and First Name

© Copyright PeopleSoft Corporation 2007. All rights reserved. 13


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

SQL
SELECT A.OPRID
, B.EMPLID
, B.LAST_NAME
, B.FIRST_NAME
FROM PSOPRDEFN A
, PS_PERSON_NAME B
WHERE A.EMPLID = B.EMPLID
This view will be identified when doing the ‘Configure Transaction’ setup in AWE in the Ad-Hoc Approver options section.

Status Monitor:

In this example, the status monitor is showing that the AWE has determined that AM2PNA Manager is the next approver for
this particular approval process. As you can see, AM2PNA Manager is a hyperlink. If the user viewing this transaction were to
select this link they would see the approver additional information page:

Approver Additional Information Page:

© Copyright PeopleSoft Corporation 2001. All rights reserved. 14


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Email Template(s)

Anytime the AWE triggers an email notification based on the rules that are set in the Configure Transactions component, it will
construct the email based on the assigned template. Here is an example of how a template might be created:

Pay special attention to the “%” bind variables. When defining a notification in the Configure Transaction component, you will
also assign a sql object that will be used to populate these binds. Notice that %1 is used as the bind placeholder for a link to an
application component. This is a requirement of the AWE. The AWE reserves the %1 bind for an auto generated link. If you
do not wish to display a link in your email, exclude the %1 bind.
© Copyright PeopleSoft Corporation 2007. All rights reserved. 15
Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Note: The actual reservation for the %1 bind made by the AWE is done by taking the smallest SeqNo value on the
WL_TEMPL_GEN_TK record. Since SeqNo is not displayed on the Generic Template Definition page, it is possible to set the
%1 bind to a row that does not have the smallest SeqNo in the set. This will cause the AWE to set the application destination
link to another bind variable.

Email Template SQL Object(s)

As stated in the previous section, you must create SQL Object(s) if you wish to use binds values in your email notifications.
Below is an example of how a SQL object might be created for populating an email template:
SELECT A.TRANSACTION_NBR
, A.EMPLID
, B.NAME
, A.TRANS_DT
FROM PS_EXP_RPT_HDR A
, PS_PERSON_NAME B
WHERE A.EMPLID = B.EMPLID
AND A.TRANSACTION_NRB = :1
AND A.LINEID = :2

In this example, the AWE will look to populate the %2 bind with TRANSACTION_NBR, the %3 bind with EMPLID, the %4
bind with NAME, and the %5 bind with TRANS_DT. Also note the “:1” bind in the where clause of the SQL Object. It is a
requirement to have all of the keys from your header record (or line level record depending on the notification) bound into the
where clause. The AWE uses the header record keys to retrieve the correct row from the Sql Object.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 16


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

User Lists Definitions (Maintain User Lists)


User List object definitions are pieces of logic that, when instantiated at runtime, return a list of PeopleSoft operator IDs.
Userlists are used primarily to define who the system needs to route a transaction to at the Step level of an Approval Process
Definition. Userlists may also be used on the Configure Transactions page as well. A set of pre-defined user lists based on
typical HCM direct reports hierarchies are delivered in v. 9.0 and are described in detail in PeopleSoft Enterprise HRMS 9.0
Application Fundamentals PeopleBook, “Setting Up and Working with Approvals”

The screen shot below describes the User List object definition:

There are four types of User Lists you can define to help the system resolve who the next approver is for a given transaction. If
you decide to use the user lists delivered with AWE then you do not need to define a user list at this point.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 17


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

1. Role – The system will return all the users in the specified role to the engine at runtime. For example, you want all
Address Change requests to go to the role of HR Administrator for approval in which case anyone in that role will receive
notification of the transaction.
2. SQL Definition – You need to enter SQL Object name they have created through Application Designer. The SQL Object
must select OPRID in its select statement.
3. Query – You need to enter Query Name they have created through Application Designer. As with the SQL Definition, the
Query must select OPRID in its select statement. If you are creating the query in the Query Manager component, you must
set the Query Type value of the query to Process. Setting the Query Type value to User can cause an error.
4. Application Class – You need to provide Application Package Name and Application Class name. The application class
must Extend the PTAF_CORE:Defn:UserListBase Class. As such, the class must also have a GetUsers() method and
return an array of string containing OPRIDs.

Include User as Input – If this checkbox is turned on, then requester’s OPRID or the previous approver’s OPRID will be used
to resolve the bind variable for SQL Object and Query.

Transaction Keys as Input – If this checkbox is turned on, the transaction data record passed into the AWE will be used to
resolve the bind variable for SQL Object and Query. The two checkboxes are not mutual exclusive. It is not recommended to
check both checkboxes.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 18


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Chapter 3 - Registering Transactions in AWE

Once you have created and defined all the required objects as described in Chapter 2, you must now register your transaction in
the AWE’s approval transaction registry. You must create a unique approval process ID for each transaction and enter all the
necessary transaction specific information.

The recommended steps for setting up your transactions to use AWE are as follows:
• Approval Transaction Registry where you register your transaction in AWE
• Workflow Transactions where you link the self service transaction name to the process ID used in AWE
• Configure Transactions where you define among other things the notifications behavior for each transaction.
• Approval Process Definition where you define your approval processes and criteria, if any
• Security

All of the online components required to register transactions in AWE may be found here: Main Menu  Set up HRMS 
Common Definitions  Approvals  Approvals Setup Center

© Copyright PeopleSoft Corporation 2007. All rights reserved. 19


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Register Transactions

The following is the detailed information of this Register Transactions page.

Page Header Values

Process ID (Approval Process ID) – This is a unique approval process identifier for the transaction. This unique
identifier needs be passed in when AWE is invoked by the transaction.

Description – The description of this unique approval process identifier for the transaction.

Object Owner ID – The owner ID of this specific transaction.

Cross Reference Table – This table is required and it consists of two parts: a sub record PTAFAW_XREF_SBR and
key fields of an application transaction.

Notification Options

Enable Notifications – This notification option is applied at the transaction level. It determines whether the
transaction allows notifications or not. There are four different notification options: Email, Worklist, Both or None.

Notification Strategy – There are two strategies: online and offline. For online processing, the notification will be
sent as soon as the transaction is saved. For offline processing, the notification will be sent in a scheduled batch.

Use Email Approvals – If this box is checked, then an HTML email with an embedded form will be generated and
sent to a recipient. The recipient can take an action on the transaction within the email itself without having to log into
the system. For detailed information on email collaboration, click here.

Form Generator Package Root and Form Generator Class Path – If Use Email Approvals is checked, an
Application Package Name and Class Name need to be provided here.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 20


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Default Approval Component

Menu Name/ Approval Component – This is the default approval location for your transaction. It identifies the
default component that users should go to when selecting a worklist entry. The assumption here is that each transaction
will have at least one page or component where the user must go to in order to approve the transaction. That
component – whether already existing in the database or new – should be entered here.

Approval Event Handler Class

Root Package ID/Path – Use these two fields to point to the location of your approval event handler class as
described in the Event Handler section of this document.

Approval Status Monitor

Adhoc Package/Adhoc Class – Use these two fields to point to the location of your Adhoc Access class as described
in the Adhoc Access section of this document.

Thread Package/Thread Class – Use these two fields to point to the location of your Thread Class as described in
Thread Package of this document.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 21


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Transaction Approval Levels

Level – Select Header or Line, which determines the levels that are enabled by the application for approvals. The first
row will always be the header level. In the majority of cases, you need only define a header level. Select “Header” to
describe your Header Record. If your transaction supports line level approvals, you will add an additional row and
select “Line” to describe your line level record.

Record Name- Select your header record name in the row that you marked as “Header” level and your line level
record name in the row you marked as “Line”.

Level Record Key Field Label IDs – When you define the record names for each level in your transaction (under the
Transaction Approval Levels Section), the Level Record Key Field Label IDs section is automatically populated with
the key fields from each of the records you defined. You select from the list of available field label IDs for the AWE to
use as a default label anytime it is displaying those key values.

You can define criteria against only the fields that are defined here.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 22


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Workflow Transactions

Once the transaction is registered under an AWE Approval Process ID, the transaction must now be linked to an HCM
Transaction Name in the EO_TRANSACTIONS record. This will allow you to leverage the deprecated approvals
configuration without incurring major functional regression. For example, if the transaction is currently configured to update
core records upon final approval via a component interface, you can still leverage these configuration values. Also, this step
will allow integration with other HCM Common Applications that require an HCM transaction name, for example, HCM Direct
Reports Common UI. Even if the transaction you are registering does not use any workflow, you must still execute this step
because it is required for both AWE and Delegation.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 23


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Configure Transactions

Now that the transaction is registered, the configuration options for the transaction can be set. The following is the detailed
information for the Configure Transactions page. Configure Transactions component is used to select and define elements that
determine what triggers a notification, who receives the notification, and the content of the notification.

Ad Hoc Approver Options

Approval User Info View – Select the Approval User Info view that you created as described here.

Ad Hoc User List – Please refer to the section on creating User List Definitions for instructions on how to create an
Ad Hoc User List.

Notification Options

This section appears only if you select the Use Email Approvals check box on the Register Transactions page for the
given process ID

© Copyright PeopleSoft Corporation 2001. All rights reserved. 24


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

User Utilities

User Utilities Package/Path – The UserUtilities class’s main purpose is for delegation support. The default setting
points to PTAF_USER_UTILS:UserUtilities. This delivered default will allow the AWE to apply the delegation rules
that are set up for each user in PSOPRDEFN. However, the HCM Shared Components team has delivered another
version of this class, HCSC_USER_UTILS:UserUtilities. If you select this class path as your User Utilities location,
then the AWE will apply the delegation rules that are set up in the HCM Delegation Framework (new to 9.0).

Events

The events section of the Configure Transactions page is used for setting up notifications for your transaction. Keep
in mind that the AWE is an event centric application. Therefore, notifications are triggered by event. This section
defines the information to build the default URL to include in notification for each of the participants that you specify
in the Notifications section.

Header or Line – Select the level at which an event occurrence will trigger the notification.

Event – Select the event for triggering the notification. Available events include:
Event Name Event Description
Ad Hoc Delete When an approval step is deleted via Adhoc mode in the
status monitor

© Copyright PeopleSoft Corporation 2007. All rights reserved. 25


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Ad Hoc Insert When and approval step is added via Adhoc mode in the
status monitor
Hold Step When a step is put on hold by an approver.
Locked Out When a step is activated but the current approver’s user
account is locked out.
On Error When the AWE encounters an error
On Escalate When step is escalated based on the escalation rules
On Final Approval When the final step in an approval process is approved
On Final Denial When the final step in an approval process is denied
On Process Launch When an approval process is launched (i.e. a transaction
is first submitted)

On Reactivate When a previously ended process is re-started


On Reassign When any step in an approval process is reassigned to
another approver
On Step Complete Anytime a step is completed (Approved, Denied or
otherwise)
On Terminate When a transaction is terminated via the DoTerminate
method
Processing Complete When all stages of an approval process are complete
Push Back When a step is pushed back to the previous step in the
approval chain
Request Information When a request for more information is sent
Route for Approval Anytime the transaction is routed to an approval step
Route for Review Anytime the transaction is routed to a reviewer step

Menu Name – The default menu that is used when creating the link that will be embedded in your email notification.
If no value is entered in the row of Notification grid, then the recipient is sent to the same menu and component that is
defined for the Worklist Approval component. .

Approval Component – The default component that is used when creating the link that will be embedded in your
email notification.

Page Name - The default page that is used when creating the link that will be embedded in your email notification.

Menu Action – The default menu action that is used when creating the link that will be embedded in your email
notification.

SQL Object Identifier – The default SQL Object that will be used to populate the binds in your email notification
template.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 26


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Notifications

Main Tab
Participant – Select the Participant for whom you want the notification to be sent.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 27


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Participant Description
A-Delegate Any approver associated with the particular step who
has delegated his/her approval authority
A-Proxy Any approver who is associated with a particular step
and who has been given approval authority to serve
as a proxy.
Admin The Approvals Administrator as defined on the
approval process definition
Approvers Any approvers associated with the particular step for
which the event has been triggered.
Dynamic Any approver who was dynamically selected at a
particular step in the approval process.
R-Delegate Any approver who is associated with the particular
step and who has delegated his/her request (or
initiate) authority.
R-Proxy Any approver who is associated with a particular step
and who has been given request (or initiate) authority
to serve as a proxy.
Requester The person who requested the transaction.
Reviewers Any reviewer associated with the particular step for
which the event has been triggered
UserList A user list defined group of participants. Please
Refer to the section User List Definitions for
instructions on how to create user lists.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 28


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Channel – Select the type of notification to be sent.

Notification Type Description

Both Both Email and Worklist


Email Email only
None No notification
User Notification options on PSOPRDEFN will be used
for each individual user.
Worklist Worklist only

UserList – If UserList is selected as the notification participant, then a User List must be selected to generate the
user. Please refer to the section on creating User List definitions for instructions on how to create user lists.

Template Name – If Email or Both is selected as the Channel, then select the email template name that should be
used in the email notification.

Template Details Tab

Menu Name – For each notification that is being sent per event, you can override the default menu that is defined at
the notification level under the Events section.

Approval Component – For each notification that is being sent per event, you can override the default approval
component that is defined at the notification level under the Events section.

Page Name – For each notification that is being sent per event, you can override the default page that is defined at
the notification level under the Events section.

Menu Action – For each notification that is being sent per event, you can override the default menu action that is
defined at the notification level under the Events section.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 29


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

SQL Object Identifier – For each notification that is being sent per event, you can override the default SQL Object
Identifier that is defined at the notification level under the Events section.

Priority – Select the priority of the email being sent. Priority options are High, Medium, or Low.

Frequency Tab

Number of Hours – This is the frequency at which additional notifications will be sent to the participant for as long
as the transaction is pending his/her review.

Max Notification – The number of times for which the notification will be sent until action has been taken.

The Notification and Escalation Manager runs the batch job for these notifications and is packaged separately from
the AWE. Information on this can be found in PeopleSoft Enterprise HRMS 9.0 Application Fundamentals
PeopleBook, “Setting Up and Working with Approvals,” Setting Up the Notification and Escalation Manager.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 30


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Setup Process Definitions

Under Setup Process Definitions, you will define one or more process definitions for each of your transactions. You can define
the number of stages, paths, and steps required for each process definition. In addition, you can define criteria that the AWE
will use to determine which process definition, path, or step to use at run time.

There are two ways of telling the AWE which approval process definition to initiate. The first way is to explicitly pass the
Approval Process Definition ID to the API by setting the definition property on the LaunchManager class. The other way is to
simply not pass any Approval Process Definition ID to the LaunchManager and let the engine evaluate all possible Approval
Process Definitions that belong to the Approval Process ID that was used to instantiate Launch Manager.

Example 1- Explicitly set the Approval Process Definition ID:


&MyLaunchManager = Create LaunchManager (&AprPrcsId, &HeaderRecObject, &Oprid)
&MyLaunchManager.Definition = &MyAprDefnId;
&MyLauchManager.DoSubmit()

Example 2 – Let AWE decide:


&MyLaunchManager = Create LaunchManager (&AprPrcsId, &HeaderRecObject, &Oprid)
/*Do not set the definition property as was done above*/
&MyLaunchManage.DoSubmit()

By not explicitly setting the Approval Process Definition ID, the AWE performs the following logic to determine
which Approval Process Definition ID to use:
• If Definition Id not explicitly passed to AWE then execute Definition Criteria for each Definition Id for the
given process ID.
• If exactly 1 Definition Criteria = True, then use that Definition ID
• If more then 1 Definition Criteria = True then use the Definition ID with the highest Priority
• If 0 Definition Criteria = True then use the Definition ID marked as default

© Copyright PeopleSoft Corporation 2007. All rights reserved. 31


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

In the Setup Process Definitions component, across the top of the page are the following links:

Definition Criteria – Please Refer to the Criteria Definition section for instructions on defining Criteria Definitions.

Alert Criteria – Please Refer to the Criteria Definition section for instructions on defining Criteria Definitions.

Save As – If you are setting up multiple approval process definitions that only differ by a few attributes, you can
create the first one and then save it as many times as you like under different Approval Definition ID Names. You
can then go into those new approval definitions and make the few changes you desire. The screen shot below
demonstrates how you may use the Save As feature:

In the example above, the original Approval Definition ID was designed to select one level of approver by
Supervisor ID. By using the Save As feature, a second Approval Definition can be created also having one level by
now determining approver by Department Manager ID. The only change that will need to be made in the new
definition is that the step approver user list will now need to point to the ApproverByDeptMgr application class
based User List. This is described in more detail later on in this section.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 32


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Approval Process Viewer – The approval process viewer displays an Adobe SVG Viewer interpretation of the
selected approval process definition. This tool is used simply to create a more user-friendly display of the current
approval process. The Adobe SVG viewer must be installed on the client. As of the posting date of this document,
the install for the SVG viewer can be found at http://www.adobe.com/svg/viewer/install/main.html. The screen shot
below is an example of the SVG Viewer. By clicking on the “+” or “-“ icons, the application will take you to the
specific page where you can either add or delete stages, paths, or steps for the selected approval process definition.

Preview – This is a testing tool used to verify the routing of the approval process definition before deployment. The
preview application will prompt the user to enter all the key fields from the header record and then try to determine
the routing based on those keys. However, the success of the preview application is subject to level of complexity
in your design. For example, if you use application class based userlists that require runtime data (i.e., leveraging
the UserListAttibutes class), the preview application will not be able to determine the approval path accurately.

Preview User - The User ID of who will act as the Requester of the test transaction.

Transaction Number - This is the key field from the transaction’s header record.

See Question #8 in the Frequently Asked Questions section for details on how to use this functionality.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 33


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Process ID – The approval process ID as defined in the Register Transactions page.

Definition ID – The name of the approval process that was determined upon entry to this component.

Effective Date – The effective date of this approval definition ID.

Description – The description of this approval definition.

Admin Role – This is the approvals administrator for this approval definition.

Status – This is the effective status of the approval definition. Use the Deactivate/Activate button to toggle the
status of the transaction.

Priority – The priority field is used to prioritize approval definitions. This is used when a transaction invokes the
AWE using an implied approval definition ID (i.e., making the engine decide which process id to use as described
on page 30). If the AWE evaluates the Definition Criteria object as true for more then one definition, it will use the
priority field to determine which one to return.

Default Process Definition – Use this field to mark one approval definition ID under each approval process ID as
the default definition. If the AWE encounters a situation where no approval definition is found either explicitly or
implicitly, it will use the default definition.

User Auto Approval – An approver may appear more than once in the same approval process. If “User Auto
Approval” checkbox is turned on, then this approver’s action will be remembered and automatically reapplied
whenever this approver appears again in the approval chain of the transaction.

Route To Requester – If the Requester or Submitter of the transaction also appears as an approver on any
subsequent steps in the approval process, the Route to Requester flag set to “on” will require that he/she take action
on those steps. If the Route To Requester flag is set to “off”, he/she will be skipped from performing action on
those steps. Route to Requestor works in conjunction with the self-approval flag. If the approver failed to meet the
self-approval criteria, the approval could still be routed if this check box is selected. If the check box is not selected
and the approver fails to meet the self-approval criteria, then the system routes the approval to the approvals
administrator.

If self-approval is set up, the criteria to trigger self-approval is not met, and route to requester is not selected, then
the requester can't be included as part of the approval path.

If route to requester is selected and self-approval criteria are not met, then the requester is included as part of the
approval path and the system notifies them of the pending approval.

Stages / Paths / Steps

© Copyright PeopleSoft Corporation 2001. All rights reserved. 34


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Stages – A stage is a high level grouping of approval paths. Paths within the same stage are carried out in parallel.
In order to achieve sequential path processing, paths need to belong to separate stages.

Paths – Approval Paths are logical groupings of approval steps. Again, paths belonging to the same stage are
carried out in parallel.

Source – There are two source types that can be assigned to a path: Static and Dynamic. A Static source
allows users to define a static number of approval steps and it indicates that you want the system to use the
individual user-defined steps when it processes an approval. A dynamic source type only allows users to
define one step and requires no step criteria. The AWE will dynamically figure out whether or not to route the
transaction to next level or approver(s). When using the Dynamic source, the system uses the user list on the
step definition to initialize the steps in the path. The single step definition is repeatedly run, until the step's
user list returns no more approvers. All these instances are queued in sequence. It is expected that HCM
customers will predominately use the Static source.

Details – The path details sub-page allows users to define more granular information about the Path.

Skip Prior Steps for Requester - Select to indicate that if one of the approvers in this path is also the
requester, then the system is to skip all steps in this path prior to that approver’s step.

Notify Admin on No Approvers – This checkbox only shows up if the path is dynamic (HCM transactions
will be mostly static). This check box will send a notification to the Administrator of the entire path is
skipped due to a lack of approvers for all steps. If it is a dynamic path and you select to notify the Admin on
No Approvers, this will only fire if the AWE determines that there are no approvers for that step and it is the
last step in the process.

Timeout Options – The time out options section is used to manage escalations for the path when no action
has been taken.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 35


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Escalate Options – There are three escalation actions that you can choose from: Advance Approval, Notify
Participant, or Reassign Approval.
Escalation Option Description
Advance Approval Pushes the approval to the next step in the path. If
a user list is specified, those users will be notified
Notify Participant Will send a notification to the participant
generated by the corresponding user list
Reassign Approval Will reassign the step to the participant generated
by the corresponding user list

Hours/Days – Specifies the time after which the escalation option will execute.
User List – Used to generate the participant for whom a notification will be sent. Used only for the
Notify Participant or Reassign Approval options. Refer to the section on creating User List Definitions
for instructions on how to create user lists.

Steps – Steps represent the individual approval steps within a path:


Approver User List – Specify the user list to be used to generate the approver participants for each step.
Please refer to the section on creating User List Definitions for instructions on creating user lists.
Details – The step details sub-page allows users to specify more granular information about the step.

Approver Role Name – In addition to the Approver User List, a PeopleSoft Role may be entered as
additional approvers. You must enter either a user list or a user list and role. You cannot enter just a role by
itself.
Approver Requirements – In the case that the step has more then one possible approver, one of these three
rules will be followed:
All Approvers Required – Every approver generated by the Approver User List and/or Approver
Role Name will have to approve this step before the transaction can proceed.
Some Approver Required/Number of Approvers Needed – If more then one approver is
generated for the step, a minimum number of approvals can be specified in order for the transaction
to proceed. For example, if five approvers were generated by the user list, you could specify that
only two of the five need to approve the transaction before it can proceed.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 36


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Self Approval – In the case where the approver for this step is also the requester of the transaction, if this
flag is checked, then the step will be skipped. In other words, the step assumes approval since the approver is
the one who created the transaction.
You can establish a criterion that controls the requester's approval authority by using the Self-Approval
Criteria link. If the associated criteria evaluate to true, then self-approval is acceptable. For example, you can
place a limit on the dollar amount for the requester so that if the transaction is over that amount, the requester
is not used as an approver.
If you select self-approval and the requester appears as an approver, the criteria are evaluated. If the criteria
are met, then the requester's approval is assumed and the minimum approvers for that step decrements by one.
If the criteria are not met, the Approval Workflow Engine requires that there be at least one more step after
this one in the path. This does not apply to ad hoc steps.
Note. If the criteria are not met and no later step exists, the system inserts an additional step. This selection is
then routed to the approvals administrator.
Clearing the check box means that self-approval is never acceptable. If self-approval is not enabled, then the
requester can't serve as an approver. If the requester appears as an approver for any step, the approver is
blocked from acting. If, because of this, the number of approvers that are available to act drops below the
minimum, then an error is generated. The process is then routed to the approvals administrator.
When a requester is an approver, you can configure the path to skip the steps in that path prior to the
requester's step.
Reviewer User List – A Reviewer cannot take action on a transaction but he/she can be kept in the loop for a
particular transaction using the AWE. Enter a user list to generate a person or group of people who have
access to view this transaction, but not take any action on it. Please refer to the section User List Definitions
for instructions on how to create user lists.

Step Criteria – Please Refer to the Criteria Definition section for instructions on defining Criteria Definitions.
The step criteria object is evaluated by the engine at runtime to determine if the approval step should be instantiated
or skipped.

Criteria Definitions

Criteria Definitions are used to define bits of logic that, at runtime, are evaluated for a Boolean result (True or False).
The areas in which you may set up criteria definitions include at the process definition, alerts, path and step levels. The
Criteria Definition page found at all four areas listed are the same and are in effect only used to evaluate a result that the
a developer can then use to trigger a process of some sort within the application. The generic Criteria Definition page is
described below:

From a functional standpoint, criteria may be used to determine for example which approval process definition ID to
use for a given transaction. Or to determine when to show the user a message about the transaction he/she is trying to
submit for approval.

For example, you may want employees based out of Europe earning more than $100,000 per year to have only one level
of approval for submitted promotion requests whereas for all employees in the US you want three levels of approval for
any submitted promotion request. Any criteria evaluation is possible as long as the appropriate fields exist in your
header record. If the field does not exist in your header record, you cannot run criteria against them.

There are 3 types of criteria that can be defined: Always True, Application Class, and User Entered.

Criteria Type 1 – Always True – Always true simply means that whenever the system evaluates this criteria it will
always return a ‘True’ to the engine. So whatever process you have associated with these particular criteria will always
execute.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 37


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Criteria Type II – Application Class – Allows you to define an application class to be executed at the time the criteria
are evaluated. The system displays this section when you select a Criteria Type value of Application Class. Use this
section to assign application packages as criteria for the approval process definition. When you define a class, the
system uses it along with other criteria you enter to process the approval.

Root Package ID / Application Class Path – Use these fields to point the AWE to a pre-defined criteria
application class.

There are three requirements for using Application Class based criteria:
1) The Application Class must extend then PTAF_CRITERIA:Definition:CriteriaBase class

2) The Criteria application class must have a Check() method

3) The Check() method must return a Boolean

Criteria Type III – User Defined – The User Defined criteria type allows you to set up rules based on the fields that
exist on the header record of your transaction and delivered operands using the user interface shown below.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 38


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

All Criteria Needed to Satisfy – This check box takes the place of adding “and” or “or” between each row of criteria.
If this is selected, the AWE assumes that all rows of criteria need to be met. If the check box is not checked, then the
AWE assumes that only one row of criteria needs to be met.

Record – Although this prompt table allows users to select any record in the database, only those records definitions
that have the same key values as your header record should be used. The engine uses the header record keys for the
running transaction to select for the criteria.

Field – Allows the user to select any field residing on the record that was selected.

Criteria Operator – Allows the user to select 1 of 7 operands to evaluate the value returned from the header
record.field that was defined:

Criteria Operator Definition


Between Use both value fields to specify an upper lower limit for the
field value. Fields are inclusive.
Equal Use the first value field for specifying a value for the field
specified
Greater Than Use the first value field to specify a lower limit for the field
specified
Is Blank The field specified returns no value
Is Not Blank The field specified returns any value
Less Then Use the first value field to specify an upper limit for the
field specified
Not Equal To Enter a value in the first value field that the specified field
cannot equal

Monetary Criteria – Use the monetary criteria section to define criteria logic for monetary fields only. The system
displays this section when you select the Criteria Type value of User Entered. Use this section to establish approval
criteria based on a value or amount. The system uses the values you define to determine the routing for approving the
transaction. When the system evaluates the criteria for an approval process or a step or path within the process, it uses

© Copyright PeopleSoft Corporation 2007. All rights reserved. 39


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

monetary values you define in this section. The system uses values from fields in this section in conjunction with the
Operator field to determine whether to run a step.
Amount Record -- Select the record name to be used. For example, you might use a salary field to trigger the
step.
Amount Field -- Select the field within the amount record to be used.
Currency Field -- Select the currency field that corresponds to the currency code you select in the Currency
Code field below.
Operator -- Select a value that determines how the system processes the values in the Amount fields. Values
include Between, Greater Than, and Less Than.
Amount -- Use the Amount fields to define an amount range for use with the Operator field.
Note. -- If you use the Criteria Operator with a value of Between, a second Amount field becomes active.
Currency Code -- Select the monetary unit you want to use for the approval.
Rate Type -- Select how the system arrives at the currency value, such as the current rate or a pay rate. (From
PeopleBooks).

© Copyright PeopleSoft Corporation 2001. All rights reserved. 40


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Alert Criteria

With the criteria object defined, you can then evaluate the criteria to determine if a message should be displayed on the
approval page. For example, you might define a step in your approval process to require a minimum of three approvals before
it advances to the next step. You can define your alert criteria to be true if the number of current approvals is = the minimum
minus one, which means the alert will be true if the current approver is the last approver for this particular step. You can then
decide to display a message to that approver letting him/her know that he/she is the last approver for the step.

Implementing the Status Monitor

At various points in your application, you may find it beneficial to display a graphical representation of the approval process
status for a particular transaction. Most commonly, you may want to include the Status Monitor in the Approval page itself to
educate users on who will be approving their transaction. The graphic below shows an example of a sample Status Monitor:

To implement the Status Monitor in your transaction, perform the following steps
1) Add the sub-page HCSC_MON_SBP wherever you would like the display the status monitor.

2) In an appropriate PeopleCode event, instantiate the status monitor interface class. For example

Import HMAF_AWE:ApprovalsFactory
Local HMAF_AWE:ApprovalsFactory &MyApprovalsFactory;

**Required - The HCSC_MON_WRK record contains field change PeopleCode that is expecting a Component
variable named &monitor.

Component HMAF_AWE:Interfaces:IstatusMonitor &monitor

/*Instantiate the Factory*/


&AprvFactory = Create HMAF_AW:ApprovalsFactory();
/*Instantiate the ApprovalManager object*/
&AprvMgr = &AprvFactory.getApprovalManager(&Awprcs_Id, &HeaderRec, &Operid);
/*Instantiate the Status Monitor Object*/
&Monitor = &AprvFactory.getStatusMonitor(&AprvMgr.the_inst, "A", Null);

The Parameters for the GetStatusMonitor method are as follows

© Copyright PeopleSoft Corporation 2007. All rights reserved. 41


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

a) Application Instance – The application instance can be retrieved for your transaction via the ApprovalManager
object. Use “the_inst” property.
b) Mode – Mode values are:
i. “A” for ad-hoc mode. This mode will allow the user to add ad-hoc approvers during an
approval process.
ii. “D” for display only mode. This mode will prevent the user from interacting the status
monitor.
c) Save Button Logic – The SaveButtonLogic parameter allows the application to invoke logic when the status
monitor is saved. For example, you may want to track which user inserted an ad-hoc step. In order for this
feature to be used, the application must pass an existing object that contains a method called SaveButtonLogic.
The following example shows how this is used. (Assume the existence of the class MySaveButton containing
method SaveButtonLogic();)

&MyObject = Create MyAppPackage:MySaveButton.MySaveButton()


&AprvFactory.getStatusMonitor(&AprvMgr.the_inst, "A", &MyObject);
&MyObject
When the status monitor is saved, the AWE will call &MyObject.SaveButtonLogic();

3) Call the buildHTML() method on the status monitor object and place its results in the HCSC_MON_WRK.HTMLAREA
html area.

HCSC_MON_WRK.HTMLAREA = &StatusMonitor.buildHTML();

Application PeopleCode

Now that all the necessary objects have been constructed and all the set up has been completed for the transaction, it is time to
add some PeopleCode to tie this all together. One thing to keep in mind, in most cases, is that calls to the AWE are best located
in SavePostChange PeopleCode events. If a transaction is submitted to the AWE before the transaction is saved and then an
error occurs after the call to the API, the situation could arise where the AWE is now tracking a transaction that does not exist.
So, it is wise to only call the AWE after the transaction has been successfully saved.

Below is an example of a typical transaction being submitted from a Component SavePostChange Event:
Import HMAF_AW:ApprovalsFactory
Local HMAF_AW:ApprovalsFactory &MyApprovalsFactory;

/*Collect the values you need for launching the transaction*/


&MyHeaderRec = GetLevel0()(1).GetRecord(Record.EXP_RPT_HDR)
&MyApprovalProcessId = SQLExec(SELECT PTAFPRCS_ID FROM EO_TRANSACTIONS WHERE TRANSACTION_NAME =
‘HR_EXPENSES’);
&MyApprovalDefinitionId =&MyHeaderRec.PTAFDEFN_ID

/*Create your launch manager object*/


&MyLaunchManager = &MyApprovalsFactory.getLaunchManager(&MyApprovalProcessId,
&MyHeaderRec,%OperatorId)

/*If you have a definition id, use it…otherwise, the engine will try to figure out which one based on the Definition Level
Criteria Object*/
If all(&MyApprovalDefinitionId) then
&MyLaunchManager.DEFINITION = &MyApprovalDefinitionId

© Copyright PeopleSoft Corporation 2001. All rights reserved. 42


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

end-if;

/*For multiple job support, we need to pass the UserListAttribute class to the engine*/
/*Create and populate Attrib RecObject */
&MyAttribRec = CreateRecored(Record.HCSC_UATRIB_SBR)
&MyAttribRec.Oprid.Value = %OperatorId
&MyAttribRec.Emplid.Value = &MyHeaderRec.EmplId.Value;
&MyAttribRec.Empl_Rcd.Value = &MyHeaderRec.Empl_Rcd.Value;

/*Create Attrib Class and assign your Attrib Rec object to the UtilsRec property*/
&MyAttribClass = Create HCSC_USERLIST_UTILS:UserListAttrib();
&MyAttribClass.UtilsRec = &MyAttribRec;

/*Pass AttribClass to the AWE*/


&MyLaunchManager.SetAttributeObject(&MyAttribClass);

/*Submit your transaction*/


&MyLaunchManager.DoSubmit();

Below is an example of what the approval component SavePostChange PeopleCode might look like:
Import HMAF_AW:ApprovalsFactory
Local HMAF_AW:ApprovalsFactory &MyApprovalsFactory;

/*Collect the values you need for acting on the transaction*/


&MyHeaderRec = GetLevel0()(1).GetRecord(Record.EXP_RPT_HDR)
&MyApprovalProcessId = SQLExec(SELECT PTAFPRCS_ID FROM EO_TRANSACTIONS WHERE TRANSACTION_NAME =
‘HR_EXPENSES’);

/&Assume we populate this derived field with a value of A for approve, D for deny, or P for pushback depending on
which button the user presses*/
&Action = &DerivedRecord.Action.Value

/*Create your launch manager object*/


&MyApprovalManager = &MyApprovalsFactory.getApprovalManager(&MyApprovalProcessId,
&MyHeaderRec,%OperatorId)
/*Notice we don’t need a an Approval Definition Id, the AWE now derives this from the Process Id and the header record
keys*/

Evaluate &Action
When “A”
&MyApprovalManager.DoApprove()
Break;
When ”D”
&MyApprovalManager.DoDeny()
Break;
When “P”

© Copyright PeopleSoft Corporation 2007. All rights reserved. 43


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

&MyApprovalManager.DoPushBack()
Break;
End-Evaluate;

Below is an example on how to invoke the status monitor. The status monitor can be used on any page provided you have the
HCSC_MON_SBP on the page:

Import HMAF_AW:ApprovalsFactory
Local HMAF_AW:ApprovalsFactory &MyApprovalsFactory;

/*Instantiate the Factory*/


&AprvFactory = Create HMAF_AW:ApprovalsFactory();
/*Instantiate the ApprovalManager object*/
&AprvMgr = &AprvFactory.getApprovalManager(&Awprcs_Id, &HeaderRec, &Operid);

/*Instantiate the Status Monitor Object*/


&StatusMonitor = &AprvFactory.getStatusMonitor(&AprvMgr.the_inst, "A", Null);

/*Set the HTML area on the sub-page = to the HTML returned from buildHTML()*/
HCSC_MON_WRK.HTMLAREA = &StatusMonitor.buildHTML();

Security

Permission Lists and Roles

The HCM Shared Components team delivered three new permission lists and one new role in the 9.0 release. Refer to the table
below for details on these objects.

Permission List Name Description Grants Roles Attached To


HCCPSCAW1010 AWE Administrator and Everything under Setup AWE Administrator
Configuration objects HRMS-> Common
Definitions->Approvals-
>Approvals Setup
Center
HCCPSCAW1020 AWE Manager Objects Job Picker Page, Manager
Delegation Picker Page,
Review Transactions
Page on the Manager
Self Service Page
HCCPSCAW1030 AWE Employee Objects Job Picker Page, Employee
Delegation Picker Page,
Review Transactions
Page on the Employee
Self Service Menu

© Copyright PeopleSoft Corporation 2001. All rights reserved. 44


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Role Name Description Permission Lists


AWE Administrator AWE Administrator and HCCPSCAW1010
Configuration objects

The general guidance for leveraging these objects is as follows


1. HCCPSCAW1030 – Employee Permission List – This list will come delivered attached to the Employee role. Any of your
application specific users who are considered employees should have the Employee role and therefore should inherit this
permission. You should not have to do anything with this object.
2. HCCPSCAW1020 – Manager Permission List – This list will come delivered attached to the Manager role. Any of your
application specific users who are considered managers should have the Manager role and therefore should inherit this
permission. You should not have to do anything with this object.
3. HCCPSCAW1010 – Administrator Permission List – This list will come delivered attached to the AWE Administrator
role. Each application should attach this permission list to any existing, application specific administrator role in order to
inherit this permission list. You should react to this object.
4. AWE Administrator – AWE administrator role – This role will be delivered attached to no users. If you do not have an
application specific administrator role, then you may leverage this role by attaching it to any application specific
administrator users you may have. If you do have an application specific administrator role, it is suggested that you simply
leverage the HCCPSCAW1010 permission list by attaching it to your role.

Web Libraries

In order for users to be able to view AWE participants' additional information via the status monitor, they must have the correct
permissions. Because of the manner in which this page is displayed, the WEBLIB_PTAF web library needs to be added to the
appropriate products permission list. All shared components permission lists will be delivered with this security already in
place. Also, in order to use the EMC functionality delivered in the AWE, permission must be granted to WEBLIB_PTAFEMC.

Permissions to web libraries are granted by performing the following steps:


1. Navigate to PeopleTools > Security > Permissions and Roles > Permission Lists > and select your desired permission
list. Under Web Libraries tab, insert a row WEBLIB_PTAF and WEBLIB_PTAFEMC into Web Libraries and then click
Edit Hyperlink.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 45


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

2. You will now see a page similar to the page shown below (depending on which web library you are granting access to.)
Click on the “Full Access” button (or, if you know which iscripts you want to limit, you can assign access at that level).

3. Make sure you click OK and then SAVE the permission list.

Appendix A. HCM Approval Workflow Engine Factory Package

As a matter of standard, the Recruiting Solutions team created a Factory Package, HMAF_AW to interface the AWE’s API in
release 8.9. The HCM Shared Components team now owns this package. HMAF_AW should be used for creating most of
your AWE Classes. The structure of the HMAF_AW package is described below:

The HMAF_AW Package is constructed of the following three parts:


1. Approvals Factory – The approvals factory class is used for retrieving the three main AWE API classes, LaunchManager,
ApprovalManager and StatusMonitor.
Method Input Parameters Returns
GetLaunchManager Approval Process Id HMAF_AW:INTERFACES:ILaunchManager
Header Record

© Copyright PeopleSoft Corporation 2001. All rights reserved. 46


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

RequesterId
GetApprovalManager Approval Process Id HMAF_AW:INTERFACES:IApprovalManager
Header Record
RequesterId
GetStatusMonitor PTAF_CORE:Engine:AppInst HMAF_AW:INTERFACES:IStatusMonitor
Mode
SaveButtonLogic

2. Interface Class – As shown in the table above, the three approval factory classes return Interface instances. These instances
are constructed within the factory by calling the corresponding HMAF_AW:WRAPPER classes.
3. Wrapper Class – The wrapper classes implement the interface class.

This concept might be confusing to those who are new to object oriented programming, but the classes are constructed this way
as a matter of standard. Keep in mind that when you call the Approvals Factory class, the class is just calling the corresponding
PTAF_AW class.

Here is an example:
&MyApprovalsFactory = Create HMAF_AW:ApprovalsFactory()
&MyLaunchManager = &MyApprovalsFactroy.getLaunchManager(&Awprcs_Id, &Hdr_Rec, &Oprid);

Is the exact same thing as calling:


&MyLaunchManager = Create PTAF_CORE:LaunchManager(&Awprcs_Id, &Hdr_Rec, &Oprid);

Appendix B. AWE Base Classes

PTAF_CORE:DEFN:UserListBase() – The UserListBase AppClass must be extended if you want create Application Class
based User Lists. Here are the methods within the class.
Methods Description Parameters
UserListAppClass The constructor of the class &rec_ --This is the userlist record
SAC_USER_LIST
GetUsers Application Developers can &prevOprid – Requester’s Oprid or
add application specific logic previous Approver’s Oprid.
to this method to retrieve
&recTxn – Application specific transaction
approver(s).
record passed into AWE.
Returns Array of String – This array will
contain the retrieved approver(s).

PTAF_MONITOR:MONITOR:threadDescrBase() – The threadDescrbase class must be extended if applications wish to create


a threadDescr class for changing the group box heading in the status monitor from the Thread keys to a more meaningful
heading.
Methods Description Parameters
threadDescr The constructor of the class None

© Copyright PeopleSoft Corporation 2007. All rights reserved. 47


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

getThreadDescr Application Developers can &keys – It contains the transaction key field
add application specific logic objects and their corresponding values.
to this method to create a
Returns String – It returns a string of the
unique title to Approval
overridden title.
Chain Graph title.

Here is an example of the effect of the threadDescr class:

Default Heading:

New Heading:

Notice how the heading changed from the Keys EMPLID, EMPL_RCD, and ACTION_DT_SS to the Transaction Title with the
requesters EMPLID (FE0001).

PTAF_MONITOR:ADHOC_OBJECTS:adhocAccessLogicBase – The adhocAccessLogicBase class must be extended if


you want to use the status monitor in your transactional pages. This will allow transaction users to add adhoc approvers and/or
adhoc approval paths. If adhoc approver is allowed, users will see a plus sign associated with both Pending and Not Routed
steps. If adhoc path is allowed, users will see a plus sign associated with each path within each stage.
Methods Description Parameters
adhocAccessLogicBase The constructor of the class None

allowInsert The method requires a &Oprid – Logon User.


Boolean return value. If it
&stepBefore – AWE’s Step instance class
returns true, then the plus
before adhoc approver is inserted.
sign will show up for each
step in the status monitor. &stepAfter – AWE’s Step instance class
Otherwise, the plus sign after adhoc approver is inserted.
won’t show up.
Returns Boolean – If it returns true, then the
plus sign will show up for each step.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 48


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

allowDelete The method requires a return &Oprid – Logon User.


value. If it returns true, then
&currentStep– AWE’s Step instance class.
the minus sign will show up
for each adhoc approval step. Returns Boolean – If it returns true, then a
It couples with allowInsert minus sign will show up for each inserted
method. If allowInsert adhoc approval step.
method returns true, then this
method should also return
true.
allowNewPath The method requires a return &Oprid – Logon User.
value. If it returns true, then
&Stage – AWE’s Stage Instance class.
the plus sign will show up for
each path within each stage. Returns Boolean – If it returns true, then a
plus sign will show up for each path
OnAdHocInsert This is actually an event. &stepinst -- AWE’s Adhoc Step instance
Application developers can class.
add code here for their
&approver – Array of strings containing
transactions upon this event.
approvers’ oprids.
OnAdHocDelete Same as above. &stepinst -- AWE’s Adhoc Step instance
class.

PTAF_CORE:ApprovalEventHandler() – The ApprovalEventHandler class must be extended if you want to extend event
processes beyond the AWE. For HCM, this is accomplished by extending the
HMAF_AWE:WRAPPERS:ApprovalEventHandlerClass() The ApprovalEventHandler class has quite a few methods. Each
method has an AWE class as its parameters, such as step instance class, application instance class. Some of the properties in
these classes will be explained below so that application developers can better utilize the information contained in these classes
when they add transaction specific code to these methods.

PTAF_CORE:ApprovalEventHandler
Methods Description Parameters
ApprovalEventHandler The constructor of the class None
OnProcessLaunch This is the first event to be &appInst – AWE’s application instance
triggered. It occurs in submit class.
or resubmit operation.
OnStepActivate This event is triggered when &stepinst -- AWE’s Step instance class.
a request is submitted or
when a prior step is
approved. Only when a step
is activated, an approver can
take action on a step.
OnStepComplete This event is invoked when &stepinst -- AWE’s Step instance class.
the minimum number of
approvers (as configured)
approves this step.
OnPushback This fires when an approver &userinst -- AWE’s User Step instance class
pushes the approval back to
the prior approved step.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 49


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

OnReactivate This is the reverse of &stepinst -- AWE’s Step instance class.


pushback. This event is
triggered when the approver
who received the pushback
again approves.
OnHeaderApprove This event is triggered when &appInst – AWE’s application instance
the approval process is over. class.
The request is finally
approved by the last approver
on the approval chain.
OnHeaderDeny This event triggers when an &userinst -- AWE’s User Step instance
approver denies the request at class.
the header level. The denial is
final and no further approval
routings are attempted from
that point. In case of line
level approval, all lines are
denied.
OnLineApprove This event is triggered when &appInst – AWE’s application instance
a line item is finally class.
approved. This only occurs
&thread -- AWE’s thread class.
when an approval process is
configured to allow line level
actions.
OnLineDeny This event is triggered when &userinst -- AWE’s User Step instance
a line item is denied and the class.
denial is final. The approval
process continues routing
other pending lines, but not
this one.
OnAllLinesProcessed This event is triggered when &appInst – AWE’s application instance
all lines have been either class.
approved or denied. The
&thread -- AWE’s thread class.
approval process is complete.
Be aware that at least one line
item has been approved if not
all in this event.
OnTerminate This event is triggered when &appInst – AWE’s application instance
a requester chooses to class.
terminate a submitted
transaction.
OnError This event is triggered when &stepinst -- AWE’s Step instance class.
an error occurs during
approval process.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 50


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Application Instance Class – PTAF_CORE:Engine:AppInst


Property Data Type Description
mainThreadId Number This is the awthread_id field value corresponding to the main
thread of this process. It serves one of the two keys to the
application's cross-reference table.
rec record This is the cross-reference record that drives this approval process
instance.
isApproved Boolean If it is true, then the header is approved. However, if this is line
level approval, then the header never assumes this value (it
becomes "completed"). Application developers need to carefully
code around this issue.
isComplete Boolean If it is true, then the process is complete. This means all lines
have been processed (finally approved or denied). This only
applies to line level approval process.
isDenied Boolean The approval process is denied, if it is true.
isTerminated Boolean If it is true, then the approval process is terminated.
status string It is the status of approval process.
requester string The person who submits this approval transaction.
thread Thread class object The PTAF_CORE:ENGINE:Thread object corresponding to the
main cross-reference table record.
appDef Process Definition The PTAF_CORE:DEFN:AppDef object corresponding to
class object approval process definition on which this instance is based.

Step Instance Class – PTAF_CORE:Engine.StepInst


Property Data Type Description
awthread_id Number This is the awthread_id field value corresponding to the main
thread of this process. It serves one of the two keys to the
application's cross-reference table.
awstep_instance Number This is the unique step instance number for this step instance.
This key is globally unique and serves one of the keys for the
step instance.
original_approvers Array of strings. Approvers who are supposed to take action on the submitted
transactions.
actual_approvers Array of strings. Approvers who have or will actually taken action on the
submitted transactions. They are referred to as proxies or
alternate approvers.
rec record The transaction record passed into AWE.
isPending Boolean If it is true, then this step is pending approval.
status string It is the step status of approval process.
isOnHold Boolean If it is true, then someone has placed this step on hold for
approval/denial at a later date.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 51


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

User Step Instance Class – PTAF_CORE:Engine:UserStepInst


Property Data Type Description
approver string. A person who has or will actually taken action on the submitted
transaction.
original_approver string. A person who is supposed to taken action on the submitted
transaction.
isApproved Boolean If it is true, then the step is approved.
isPending Boolean If it is true, then this step is pending approval.
status string It is the step status of approval process.
isOnHold Boolean If it is true, then someone has placed this step on hold for
approval/denial at a later date.
isPushedBack Boolean If it is true, then the step has been pushed back.
rec record User instance record: PTAF_USERINST.
thread Thread class object The PTAF_CORE:ENGINE:Thread object corresponding to the
main cross-reference table record.
step Step instance class The PTAF_CORE:ENGINE:StepInst object.
object

© Copyright PeopleSoft Corporation 2001. All rights reserved. 52


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Frequently Asked Questions

Question # 1: What is the Notifications feature and how is it used?

Answer:

The Notifications feature can be found under Configure Transactions as shown below. It is used as a reminder service for
notifying participants who have not responded to a particular transaction or request. You can set the number of hours and total
max number of times to notify each participant by event (i.e., on Final Approval notify the Requester every 2 hours, not to
exceed 5 notifications). The notification is trigged only if the participant has not acted on the transaction or request.

Question # 2: What is the Timeout or Escalation option and how is it used?

Answer:

The Timeout Options can be found at the Path level under the Details link under Setup Process Definition as shown below.
You can use this feature to define what should happen to a particular transaction after a certain period of time. For instance,
you can define to notify the participant, advance the approval, or reassign the approval after a certain number of hours or days
have passed. You can have the request reassigned to a particular person in the database or to a predefined User list. This
option should be used for time sensitive transaction.

Question # 3: What is “OnHeaderApprove”?

Answer:

OnHeaderApprove is a specific event in AWE that is fired in the event handler once a transaction or request hits the Final
Approval step in the approval process.

Question # 4: Where are the new pre-defined Direct Reports User Lists?

Answer:

© Copyright PeopleSoft Corporation 2007. All rights reserved. 53


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Navigate to Setup HRMS  Common Definitions  Approvals  Approvals Setup Center  Maintain User Lists. Click to
Add a New User List. The new User Lists for Direct Reports can be found under the HCSC_USERLIST_UTILS application
class Root Package ID.

Click on the Application Class Path lookup to see the 5 application classes. Note that their names still contain strings that are
not production worthy. Developers should have their functional analysts to determine what name should be entered in the
Description field for each user list definition.

It is important to be clear with the naming convention on the Description field of the User List Definition page as shown below.
The Description field shows up right under the Approver's name in the Approval Graphic representation (Status Monitor) as
shown in the green screen shot below.

Question # 5: Will there be an archiving mechanism delivered for AWE?

Answer:

© Copyright PeopleSoft Corporation 2001. All rights reserved. 54


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

We are not delivering any specific feature for archiving transactions stored in the AWE. We recommend that customers use the
PeopleTools Archive Manager component.

Question # 6: Will a batch job run at night for escalations and timeouts?

Answer:

You must use the Escalation and Notification Manager, which is bundled separately from AWE.

See PeopleSoft Enterprise HRMS 9.0 Application Fundamentals PeopleBook, “Setting Up and Working with Approvals,”
Setting Up the Notification and Escalation Manager.

Question # 7: What do the scrolling arrows on the Setup Process Definition page do?

Answer:

Allows the user to sort the list in either ascending or descending order.

Question # 8: What is the Preview User feature all about?

Answer:

Preview User serves as a preview tester of your Approval Definition ID. It allows you to run a “what if” scenario using any
person in the database as the Requester for any Definition ID. You can walk through step by step to see to whom the
transaction is routed at each level of the Definition ID.

Preview User can be found under Setup Process Definition. After selecting a Definition ID, click on the “Preview” link in the
upper right hand corner of the page (see below).

© Copyright PeopleSoft Corporation 2007. All rights reserved. 55


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

You must enter a valid ID in the Preview User lookup field. The Search box represents all the key fields defined in the header
record for the particular Definition ID you are using. Click Search and all the transactions associated with the Definition ID are
listed.

Click on any one of the transactions and receive the following page:

© Copyright PeopleSoft Corporation 2001. All rights reserved. 56


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

The top of the page describes the values used for the transaction chosen. The Approve and Deny buttons represent the action
you can take to see how the approval will progress at each level. This is just a test page so no notifications will be triggered and
the transaction itself will not be modified in any way.

The Status Monitor shown here is the route the transaction would take if the Preview User you selected on the previous page
had requested the transaction.

Also shown on this page is xml code that describes the approval process definition itself that developers could use for
troubleshooting.

Question # 9: How does the Pushback event differ from the Restart, Resubmit, or Request for More Information
events?

Answer:

Pushback - Allows the user to push the transaction back only one step but not back to the Requester. The transaction
cannot be modified while it is being pushed back. The classic use case for Pushback is when a senior level person prefers
having someone below him deny the transaction instead of him doing so.

Restart - Cycles a pending transaction back through the approval process beginning with the 1st approver. AWE treats
this as a new transaction. The classic use case for Restart is when there has been a change in the approval chain (resignation,
transfer, etc.) so the transaction must go through the same approval process to document the different people now holding those
positions.

Resubmit - Cycles a non-pending transaction (i.e., denied, approved, terminated, etc.) back through the approval process
beginning with the 1st approver. AWE treats this as a new transaction. The classic use case for Resubmit is similar to that of
Restart except it involves transactions that are no longer pending. This is mostly done by the Admin but can be exposed to the
self-service user.

Request for More Information - Allows the user to send the transaction to any body in the database while placing the
transaction in a Hold status. No one can take action on the transaction except for the person who requested more
information. The classic use case for Request for More Information is when a manager receives a request for a laptop but wants
to make sure we are using the correct vendor so he puts the transaction on hold while sending it to someone either in the
approval chain or not. Only he can change the status of the transaction, no one else. Once he receives the confirmation he
needs, he can go back into the transaction and either accept or deny it. The application developer can restrict the persons that
he can send the transaction to by using the 'getallactiveparticipants' method, which will expose only those who are a part of the
approval chain for the given transaction.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 57


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Question # 10: What changes have been made to the Approvals menus?

Answer:

The setup components for the Approval Workflow Engine can still be found under:

Setup HRMS  Common Definitions  Approvals  Approvals Setup Center

The maintenance components for the Approval Workflow Engine can now be found under:

Workforce Administration  Self Service Transactions  Approvals and Delegation

Breaking apart the setup components from the maintenance components allows the customer to limit exposure of the setup
components, which if tampered with, could cause serious problems with approval transactions.

Question # 11: What does the Default Process Definition ID checkbox do and how does that relate to effective dating a
Definition ID?

Answer:

Under the Setup Process Definition menu, you can check the Default Process Definition checkbox for a particular Definition
ID.

© Copyright PeopleSoft Corporation 2001. All rights reserved. 58


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

The assumption is that customers will have multiple Definition IDs for every Process ID registered with AWE. So then how
does the AWE know which Definition ID to use?

When a transaction is submitted, AWE first looks at any criteria definitions set up at the Definition ID level. If the transaction
submitted does not match a Definition ID based on defined criteria, then it uses the Definition ID that has the Default Process
Definition checkbox checked.

If there is at least two Definition IDs that are both “Active” and are current based on effective date, the AWE will use the
Definition ID that has the Default Process Definition checkbox checked.

Question # 12: Is there a way to port Approval Process Definitions across PeopleSoft databases or instances?

Answer:

This can only be done using Datamover scripts.

Question # 13: Can you give an example of how Criteria Definitions are intended to be used?

Answer:

All links for Criteria Definition in the application take you to the same page -- the Criteria Definition page. This is where you
define criteria for whatever object the link indicates you are defining for. Approval Process Definition Criteria, Alert Criteria,
Path Criteria, Step Criteria, and Authorization Criteria are all just criteria definitions. A criteria definition is no more than a
piece of arbitrary logic that, when evaluated, returns true or false. Anytime the AWE tries to launch an approval process, the
first thing it does is evaluate the criteria definition that is tied to the approval process definition. If it returns false, then it wont
use it. Then it looks at the criteria for paths in order and uses the first path that has a criteria definition that resolves to true, and
so on. Alert criteria, although the same in principal, is a bit different in application. An application developer can leverage
alert criteria to decide when to display an alert on the page for the user. For example, for a Promotion, you may decide to
display a warning message to the user if he/she tries to promote an employee to a job that pays more than 50%.

Question # 14: Was there a version of the AWE already delivered in a previous version of HCM?

Answer:

In v. 8.9, a lighter version of the AWE (compared to what is delivered in 9.0) was tightly coupled with both HCM Recruiting
Solutions and HCM Absence Management to process approvals for only those two specific applications. No other applications
in HCM used the AWE until v. 9.0. Applications using the new AWE for process approvals in 9.0 include: eProfile, eProfile
Manager, Recruiting Solutions, Absence Management, Job Profile Manager (new), Enterprise Learning Management, and
ePerformance.

© Copyright PeopleSoft Corporation 2007. All rights reserved. 59


Approval Workflow Engine (AWE) for HCM 9.0 4/18/2007

Revision History

Authors

Vincent Pallari, Senior Applications Developer, HCM Shared Components Team

Renli Wang, Senior Applications Developer, HCM Shared Components Team

Robbin Velayedam, Senior Principal Product Manager, HCM Shared Components Team

Reviewers

The following people reviewed this Red Paper:


Jennifer Crabb
Amy Easland
Kevin White

Revision History
1. 07/01/2006: Created document.
2. 02/01/2007: Revised document
3. 02/05/2007: Revised document
4. 04/18/2007: Revised document

© Copyright PeopleSoft Corporation 2001. All rights reserved. 60