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 Related Materials 4 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. 5

© Copyright PeopleSoft Corporation 2007. All rights reserved.

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

4/18/2007

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 In the following example, EXP_RPT_HDR would be your header record.

4/18/2007

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 crossreference 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. b. PTAFCOUNTERNAME = to the name of your cross reference record 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
&MyHdrRec.SelectByKeys() &MyHdrRec.Status.Value = &MyHdrRec.Update() End-Method “D”

4/18/2007

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 = &MyHdrRec.Update() End-Method “A”

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 = &MyHdrRec.Update() End-Method “A”

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) | “ End-method; “ | &MyHdrRec.Trans_Dt.Value;

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

4/18/2007

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

4/18/2007

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

2. 3.

4.

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 Set up HRMS

All of the online components required to register transactions in AWE may be found here: Main Menu 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 Ad Hoc Delete Event Description 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 Hold Step Locked Out On Error On Escalate On Final Approval On Final Denial On Process Launch

When and approval step is added via Adhoc mode in the status monitor When a step is put on hold by an approver. When a step is activated but the current approver’s user account is locked out. When the AWE encounters an error When step is escalated based on the escalation rules When the final step in an approval process is approved When the final step in an approval process is denied When an approval process is launched (i.e. a transaction is first submitted)

On Reactivate On Reassign On Step Complete On Terminate Processing Complete Push Back Request Information Route for Approval Route for Review

When a previously ended process is re-started When any step in an approval process is reassigned to another approver Anytime a step is completed (Approved, Denied or otherwise) When a transaction is terminated via the DoTerminate method When all stages of an approval process are complete When a step is pushed back to the previous step in the approval chain When a request for more information is sent Anytime the transaction is routed to an approval step 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 A-Delegate A-Proxy

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

Admin Approvers Dynamic R-Delegate

R-Proxy

Requester Reviewers UserList

© Copyright PeopleSoft Corporation 2001. All rights reserved.

28

Approval Workflow Engine (AWE) for HCM 9.0 Channel – Select the type of notification to be sent.

4/18/2007

Notification Type Both Email None User Worklist

Description Both Email and Worklist Email only No notification Notification options on PSOPRDEFN will be used for each individual user. 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 In the Setup Process Definitions component, across the top of the page are the following links:

4/18/2007

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 Advance Approval Notify Participant Reassign Approval Description Pushes the approval to the next step in the path. If a user list is specified, those users will be notified Will send a notification to the participant generated by the corresponding user list 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 Between Equal Greater Than Is Blank Is Not Blank Less Then Not Equal To

Definition Use both value fields to specify an upper lower limit for the field value. Fields are inclusive. Use the first value field for specifying a value for the field specified Use the first value field to specify a lower limit for the field specified The field specified returns no value The field specified returns any value Use the first value field to specify an upper limit for the field specified 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 Alert Criteria

4/18/2007

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

4/18/2007

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
end-if;

4/18/2007

/*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
&MyApprovalManager.DoPushBack() Break; End-Evaluate;

4/18/2007

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 HCCPSCAW1010

Description AWE Administrator and Configuration objects

Grants Everything under Setup HRMS-> Common Definitions->Approvals>Approvals Setup Center Job Picker Page, Delegation Picker Page, Review Transactions Page on the Manager Self Service Page Job Picker Page, Delegation Picker Page, Review Transactions Page on the Employee Self Service Menu

Roles Attached To AWE Administrator

HCCPSCAW1020

AWE Manager Objects

Manager

HCCPSCAW1030

AWE Employee Objects

Employee

© Copyright PeopleSoft Corporation 2001. All rights reserved.

44

Approval Workflow Engine (AWE) for HCM 9.0 Role Name AWE Administrator Description AWE Administrator and Configuration objects Permission Lists HCCPSCAW1010

4/18/2007

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

2.

3.

4.

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 GetLaunchManager Input Parameters Approval Process Id Header Record Returns HMAF_AW:INTERFACES:ILaunchManager

© Copyright PeopleSoft Corporation 2001. All rights reserved.

46

Approval Workflow Engine (AWE) for HCM 9.0

4/18/2007

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

2. 3.

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. 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 UserListAppClass GetUsers Description The constructor of the class Application Developers can add application specific logic to this method to retrieve approver(s). Parameters &rec_ --This is the userlist record SAC_USER_LIST &prevOprid – Requester’s Oprid or previous Approver’s Oprid. &recTxn – Application specific transaction 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 threadDescr Description The constructor of the class Parameters None

© Copyright PeopleSoft Corporation 2007. All rights reserved.

47

Approval Workflow Engine (AWE) for HCM 9.0

4/18/2007

getThreadDescr

Application Developers can add application specific logic to this method to create a unique title to Approval Chain Graph title.

&keys – It contains the transaction key field objects and their corresponding values. Returns String – It returns a string of the overridden 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 adhocAccessLogicBase allowInsert Description The constructor of the class The method requires a Boolean return value. If it returns true, then the plus sign will show up for each step in the status monitor. Otherwise, the plus sign won’t show up. Parameters None &Oprid – Logon User. &stepBefore – AWE’s Step instance class before adhoc approver is inserted. &stepAfter – AWE’s Step instance class after adhoc approver is inserted. Returns Boolean – If it returns true, then the plus sign will show up for each step. 48

© Copyright PeopleSoft Corporation 2001. All rights reserved.

Approval Workflow Engine (AWE) for HCM 9.0

4/18/2007

allowDelete

The method requires a return value. If it returns true, then the minus sign will show up for each adhoc approval step. It couples with allowInsert method. If allowInsert method returns true, then this method should also return true. The method requires a return value. If it returns true, then the plus sign will show up for each path within each stage. This is actually an event. Application developers can add code here for their transactions upon this event. Same as above.

&Oprid – Logon User. &currentStep– AWE’s Step instance class. Returns Boolean – If it returns true, then a minus sign will show up for each inserted adhoc approval step.

allowNewPath

&Oprid – Logon User. &Stage – AWE’s Stage Instance class. Returns Boolean – If it returns true, then a plus sign will show up for each path &stepinst -- AWE’s Adhoc Step instance class. &approver – Array of strings containing approvers’ oprids. &stepinst -- AWE’s Adhoc Step instance class.

OnAdHocInsert

OnAdHocDelete

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 ApprovalEventHandler OnProcessLaunch Description The constructor of the class This is the first event to be triggered. It occurs in submit or resubmit operation. This event is triggered when 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. This event is invoked when the minimum number of approvers (as configured) approves this step. This fires when an approver pushes the approval back to the prior approved step. Parameters None &appInst – AWE’s application instance class. &stepinst -- AWE’s Step instance class.

OnStepActivate

OnStepComplete

&stepinst -- AWE’s Step instance class.

OnPushback

&userinst -- AWE’s User Step instance class

© 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 pushback. This event is triggered when the approver who received the pushback again approves. This event is triggered when the approval process is over. The request is finally approved by the last approver on the approval chain. This event triggers when an approver denies the request at 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. This event is triggered when a line item is finally approved. This only occurs when an approval process is configured to allow line level actions. This event is triggered when a line item is denied and the denial is final. The approval process continues routing other pending lines, but not this one. This event is triggered when all lines have been either approved or denied. The approval process is complete. Be aware that at least one line item has been approved if not all in this event. This event is triggered when a requester chooses to terminate a submitted transaction. This event is triggered when an error occurs during approval process.

&stepinst -- AWE’s Step instance class.

OnHeaderApprove

&appInst – AWE’s application instance class.

OnHeaderDeny

&userinst -- AWE’s User Step instance class.

OnLineApprove

&appInst – AWE’s application instance class. &thread -- AWE’s thread class.

OnLineDeny

&userinst -- AWE’s User Step instance class.

OnAllLinesProcessed

&appInst – AWE’s application instance class. &thread -- AWE’s thread class.

OnTerminate

&appInst – AWE’s application instance class.

OnError

&stepinst -- AWE’s Step instance class.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

50

Approval Workflow Engine (AWE) for HCM 9.0 Application Instance Class – PTAF_CORE:Engine:AppInst Property mainThreadId Data Type Number Description 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. This is the cross-reference record that drives this approval process instance. 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. 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. The approval process is denied, if it is true. If it is true, then the approval process is terminated. It is the status of approval process. The person who submits this approval transaction. The PTAF_CORE:ENGINE:Thread object corresponding to the main cross-reference table record. The PTAF_CORE:DEFN:AppDef object corresponding to approval process definition on which this instance is based.

4/18/2007

rec isApproved

record Boolean

isComplete

Boolean

isDenied isTerminated status requester thread appDef

Boolean Boolean string string Thread class object Process Definition class object

Step Instance Class – PTAF_CORE:Engine.StepInst Property awthread_id Data Type Number Description 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. 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. Approvers who are supposed to take action on the submitted transactions. Approvers who have or will actually taken action on the submitted transactions. They are referred to as proxies or alternate approvers. The transaction record passed into AWE. If it is true, then this step is pending approval. It is the step status of approval process. If it is true, then someone has placed this step on hold for approval/denial at a later date.

awstep_instance

Number

original_approvers actual_approvers

Array of strings. Array of strings.

rec isPending status isOnHold

record Boolean string Boolean

© Copyright PeopleSoft Corporation 2007. All rights reserved.

51

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

4/18/2007

© 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 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

4/18/2007

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. 2. 3. 4. 07/01/2006: Created document. 02/01/2007: Revised document 02/05/2007: Revised document 04/18/2007: Revised document

© Copyright PeopleSoft Corporation 2001. All rights reserved.

60

Sign up to vote on this title
UsefulNot useful