You are on page 1of 47

PeopleTools Workflow Answer

Book

An Oracle White Paper


July 2009

TITLE

OF

P AP E R

PeopleTools Workflow Answer Book

6/25/2011
Reference Number:
PeopleTools Product(s):

Workflow

PeopleTools Release(s):

Tools 8.44 & onwards

Revision Number:

Contains:
PeopleTools Workflow in detail
Setup & Configuration
Backend Setup related to Workflow
PIA Setup related to Workflow
Security Setup related to Workflow
Final Testing and Results

The Programs (which include both the software and documentation) contain proprietary
information; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent, and other intellectual and industrial
property laws. Reverse engineering, disassembly, or decompilation of the Programs, except
to the extent required to obtain interoperability with other independently created software or as
specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any
problems in the documentation, please report them to us in writing. This document is not
warranted to be error-free. Except as may be expressly permitted in your license agreement
for these Programs, no part of these Programs may be reproduced or transmitted in any form
or by any means, electronic or mechanical, for any purpose.
If the Programs are delivered to the United States Government or anyone licensing or using
the Programs on behalf of the United States Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS
Programs, software, databases, and related documentation and technical data delivered to
U.S. Government customers are commercial computer software or commercial technical
data pursuant to the applicable Federal Acquisition Regulation and agency-specific
supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation
of the Programs, including documentation and technical data, shall be subject to the licensing
restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable,
the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted
Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or
other inherently dangerous applications. It shall be the licensee's responsibility to take all
appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such
applications if the Programs are used for such purposes, and we disclaim liability for any
damages caused by such use of the Programs.
The Programs may provide links to Web sites and access to content, products, and services
from third parties. Oracle is not responsible for the availability of, or any content provided on,
third-party Web sites. You bear all risks associated with the use of such content. If you
choose to purchase any products or services from a third party, the relationship is directly
between you and the third party. Oracle is not responsible for: (a) the quality of third-party
products or services; or (b) fulfilling any of the terms of the agreement with the third party,
including delivery of products or services and warranty obligations related to purchased
products or services. Oracle is not responsible for any loss or damage of any sort that you
may incur from dealing with any third party.
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation
and/or its affiliates. Other names may be trademarks of their respective owners.
Open Source Disclosure
Oracle takes no responsibility for its use or distribution of any open source or shareware
software or documentation and disclaims any and all liability or damages resulting from use of
said software or documentation. The following open source software may be used in Oracles
PeopleSoft products and the following disclaimers are provided.
Apache Software Foundation
This product includes software developed by the Apache Software Foundation
(http://www.apache.org/). Copyright (C) 2000-2003. The Apache Software Foundation. All
rights reserved. Licensed under the Apache License, Version 2.0 (the License); you may
not use this file except in compliance with the License. You may obtain a copy of the
License at http://www.apache.org/licenses/LICENSE-2.0.

6/25/2011

PeopleTools Workflow Answer Book

Unless required by applicable law or agreed to in writing, software distributed under the
License is distributed on an AS IS BASIS,WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License.

OpenSSL
Copyright 1998-2005 The OpenSSL Project. All rights reserved.
This product includes software developed by the OpenSSL Project for use in the
OpenSSL Toolkit (http://www.openssl.org/).
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT AS IS AND ANY
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Helma Project
Copyright 1999-2004 Helma Project. All rights reserved. THIS SOFTWARE IS
PROVIDED AS IS AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE HELMA PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Helma includes third party software released under different specific license terms. See
the licenses directory in the Helma distribution for a list of these license.
Sarissa
Copyright 2004 Manos Batsis
This library is free software; you can redistribute it and/or modify it under the terms of the
GNU Lesser General Public License as published by the Free Software Foundation;
either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.
You should have received a copy of the GNU Lesser General Public License along with
this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA.

ICU
ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright
(c) 1995-2003 International Business Machines Corporation and others. All rights
reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the Software), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, provided that the above copyright notice(s) and this
permission notice appear in all copies of the Software and that both the above copyright
notice(s) and this permission notice appear in supporting documentation. THE
SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE
COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR
ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of
a copyright holder shall not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization of the copyright holder.
All trademarks and registered trademarks mentioned herein are the property of their
respective owners.

Suns JAXB Implementation JDSDK 1.5 relaxngDatatype.jar 1.0 License:


Copyright (c) 2001, Thai Open Source Software Center Ltd, Sun Microsystems. All rights
reserved.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

6/25/2011

PeopleTools Workflow Answer Book

W3C IPR SOFTWARE NOTICE


Copyright 2000 World Wide Web Consortium, (Massachusetts Institute of Technology,
Institut National de Recherche en Informatique et en Automatique, Keio University). All
Rights Reserved.
Note: The original version of the W3C Software Copyright Notice and License could be
found at http://www.w3.org/Consortium/Legal/copyright-software-19980720
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED AS IS, AND COPYRIGHT
HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY
OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE
SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT
HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR
DOCUMENTATION.

Table of Contents
Table of Contents ........................................................................................................................................................ 8
Chapter 1 - Introduction ........................................................................................................................................... 10
Structure of this White Paper
Related Materials
Chapter 2 - What is PeopleTools Workflow ........................................................................................................... 11
Overview
Designing Workflow
Chapter 3 - Workflow/SMTP Configuration ........................................................................................................... 13
Settings in psappsrv.cfg file to enable SMTP
Settings in psprcs.cfg file to enable SMTP
Settings in PIA to enable SMTP
Chapter 4 - Testing the tools workflow .................................................................................................................. 17

Chapter 5 Email Notifications ............................................................................................................................... 20


How to Send Notifications
Notification Templates
SMTP Guranteed
Chapter 6 Backend Setup...................................................................................................................................... 23

Chapter 7 Virtual Approver ................................................................................................................................... 33


What is Virtual Approver
Using Virtual Approver
Understanding Approval Process
Understanding Approval Rule Sets
Chapter 8 Log & Trace Files ................................................................................................................................. 41
Application Server log and Trace file
Process Scheduler log and Trace file
SMTP Log
PeopleCode and SQL trace file

Copyright 2006 Oracle, Inc. All rights reserved.

6/25/2011

PeopleTools Workflow Answer Book

Appendix A Validation and Feedback .................................................................................................................. 44


Customer Validation
Field Validation
Appendix B Revision History ................................................................................................................................ 45
Authors
Reviewers
Revision History

Chapter 1 - Introduction
This White Paper is a practical guide for technical users, installers, system administrators, and programmers who
implement, maintain, or develop applications for your PeopleSoft system. This White Paper discusses guidelines
on how to configure PeopleTools Workflow, its security setup and final testing.
Much of the information contained in this document originated within the PeopleSoft Global Support Center and is
therefore based on "real-life" problems encountered in the field.

STRUCTURE OF THIS WHITE PAPER


This White Paper provides guidance on Workflow configuration and its issues. It will provide insight on how to
troubleshoot common problems arising out of Workflow functionality and reference documentation.
Keep in mind that PeopleSoft updates this document as needed so that it reflects the most current feedback
received from the field. Therefore, the structure, headings, content, and length of this document are likely to vary
with each posted version. To see if the document has been updated since last downloaded, compare the date of
downloaded version to the date of the version posted on Customer Connection.

RELATED MATERIALS
This paper is not an implementation guide to PeopleTools Workflow. It is assumed that our readers are experienced
IT professionals, with a good understanding of SMTP and Workflow. To take full advantage of the information
covered in this document, it is recommended that to have a basic understanding of Workflow, Security, Application
Designer and how to use PeopleSoft applications.
This document is not intended to replace the documentation delivered with the PeopleTools 8.4x or 8.4x
PeopleBooks. It is recommended that prior to read this document, read the Workflow related information in the
PeopleTools PeopleBooks to ensure to have a well-rounded understanding of PeopleSoft Workflow technology.

6/25/2011

PeopleTools Workflow Answer Book

Chapter 2 - What is PeopleTools Workflow


OVERVIEW
Workflow capabilities help to efficiently automate the flow of information throughout enterprise, crossing both
application and functional boundaries. PeopleSoft Workflow consists of a powerful set of tools that enables to
automate time-consuming business processes and deliver the right information to the right people at the right time.
Activities can be merged for multiple users into flexible business processes to increase efficiency, cut costs, and
keep up with rapidly changing customer and competitive challenges.
Many of the tasks that are performed throughout the day are part of larger tasks that involve several steps and
several people. For example, when supplies are ordered, an approval process is initiated: someone else reviews the
order and either approves or denies it. If the order is approved, a purchase order is sent to the vendor. If it is denied,
notification is sent back to the person who submitted the original order. The term Workflow refers to this larger
process.
Using PeopleSoft Workflow requires defining, step by step, Business Processes. The first step in implementing
Workflow application is determining the business rules of the organization. This step involves taking fluid, subtle,
and sometimes controversial practices and defining explicit rules of operation. The trick to this step is in walking a
tightrope: business rules must be specific enough to give a solid understanding of project goals, but not so specific
that they predefine a single solutionone that might be impossible to implement, or that does not provide needed
flexibility.

DESIGNING WORKFLOW
Workflow implementation depends on the Organization and User needs. There could be multiple scenarios for
which an Organization needs to implement Workflow. There are eight basic steps on how to design and implement
Workflow as per specific needs. Following is the overview on these eight steps as these are not covered in detail in
this White paper being user specific in nature. Detailed information on these steps can be reviewed in PeopleTools
PeopleBook:
Enterprise PeopleTools 8.4x PeopleBook: Workflow Technology
Overview of Implementation Steps
1. Designing a Workflow Application
Designing a workflow application can include three main steps:

Analyze and document your business requirements.

Diagram the process flow.

Document the workflow object attributes for business processes, activities, steps, events, and email and
worklist routings.

2. Build Supporting Definitions

If the applications required for your workflow do not already exist, build the definitions that you need for
fields, records, pages, components, and menus.

11

3. Create Workflow Maps

Create the workflow maps comprising the steps, activities, and business processes required for your
workflow as determined in step one.

4. Define Roles and Role Users

Define the roles and the role users, including any Query roles, required for your workflow.

5. Define Worklist Records

Create a record definition that will be used to store all of the application-specific information for the worklist.

6. Define the Workflow Objects

This is the step in which you define the workflow application. You enter each of the objects onto a business
process definition in Application Designer as determined in step one.

7. Define Event Triggers

Define the business rule in PeopleCode on the triggering application record definition.

8. Test

Test your workflow, or use the workflow monitoring tools in Workflow Administrator to validate worklist
routing results.

6/25/2011

PeopleTools Workflow Answer Book

Chapter 3 Workflow/SMTP configuration


SETTINGS IN PSAPPSRV.CFG FILE TO ENABLE SMTP
SMTP settings in Application Server configuration file are used if emails are sent through Application Server. For
example: sending emails from PeopleTools>>Workflow uses Application Server.

1. Following are the settings for SMTP in psappsrv.cfg file:


[SMTP Settings]
;=========================================================================
; Settings for SMTP mail
; Allow Dynamic Changes under [Domain Settings] has no effect on these controls
;=========================================================================
; Dynamic change allowed for SMTPServer
SMTPServer=specify SMTP server name here
; Dynamic change allowed for SMTPPort
SMTPPort=25 (This is always a default port)
; Dynamic change allowed for SMTPServer1
SMTPServer1= (Optional)
; Dynamic change allowed for SMTPPort1
SMTPPort1=0 (Optional)
; Dynamic change allowed for SMTPSender
SMTPSender=System default Email Address if no Sender is explicitly set
; Dynamic change allowed for SMTPBlackberryReplyTo
SMTPBlackberryReplyTo=Used by Blackberry Notification templates, for Reply To Email Address
; Dynamic change allowed for SMTPSourceMachine
SMTPSourceMachine=specify the IP address of Application Server box here
; Dynamic change allowed for SMTPCharacterSet
SMTPCharacterSet=Encoding used to encode the data, most commonly UTF-8
; Dynamic change allowed for SMTPEncodingDLL
SMTPEncodingDLL=If Customer encoding not supported by PeopleSoft, they can extend our system using this,
pointing to custom dll
13

SMTPGuaranteed=set to 1 if Integration Broker is used to route emails


SMTPTrace=SMTP high-level log file, shows Success / No Success
SMTPSendTime=Application Server send time used instead of the Mail Servers send time

SETTINGS IN PSPRCS.CFG FILE TO ENABLE SMTP


SMTP settings in Process Scheduler configuration file are used if emails are sent through Process Scheduler.
For example: An Application Engine program having code to send emails or the Process Scheduler notification
emails or sending process output to specific email addresses.
[SMTP Settings]
;=========================================================================
; Settings for SMTP mail
; All controls under SMTP Settings can be dynamically changed
;=========================================================================
SMTPServer= specify SMTP server name here
SMTPPort=25 (This is always a default port)
SMTPServer1=(Optional)
SMTPPort1=(Optional)
SMTPSender= specify the senders email address here
SMTPSourceMachine= specify the IP address of Application Server box here
SMTPCharacterSet=UTF-8 (this is the supported char set)
SMTPEncodingDLL=
SMTPTrace= set to 1 to generate SMTP Trace
SMTPSendTime=0

SETTINGS IN PIA
Workflow settings in PIA are essential to enable Workflow online.

Navigate to PeopleTools>> Workflow>>Defaults & Messages>> Set Workflow Defaults, and make sure the
Email Active checkbox is checked.

6/25/2011

PeopleTools Workflow Answer Book

Next, add email ID to an existing User Profile, PeopleTools > Security > User Profiles. Then Verify the
Worklist user routing preference is checked under the Workflow tab.

15

6/25/2011

PeopleTools Workflow Answer Book

Chapter 4 Testing the Tools Workflow


THROUGH APPLICATION SERVER
After setting the SMTP in Appserver configuration file as shown above, reload the server configuration. Set and
test the Workflow as follows:

Navigate to PeopleTools>>Workflow>>Defaults & Messages>>Worklist/Email message

Select the user to whom workflow needs to be fired in Deliver To box.

Select the Routing method of Email

Enter subject and message in the box provided and hit save.

User will get Email proving that the SMTP setup is correct.

THROUGH PROCESS SCHEDULER


1. Create Application Engine program via Application Designer having SENDMAIL Peoplecode

Log into Application Designer with valid PeopleSoft user id.

Click File>>New>Application Engine

Open the Peoplecode action of the step created by default by double clicking on it.

Put the following Peoplecode in the code area and save:

==========================
Local string &MAIL_CC, &MAIL_TO, &MAIL_BCC, &MAIL_SUBJECT, &MAIL_TITLES, &MAIL_TEXT,
&MAIL_FILES, &MAIL_FROM, &REPLYTO, &SENDER;
Local number &MAIL_FLAGS;
&MAIL_FLAGS = 0;
&MAIL_TO = "Replace with Receivers Email Address";
&MAIL_CC = "";
&MAIL_BCC = "";
&MAIL_SUBJECT = "Replace with appropriate Subject line ";
&MAIL_TEXT = "Replace with Email text";
&MAIL_FILES = "";
&MAIL_TITLES = "";
17

&MAIL_FROM = "";
&MAIL_SEP = ";";
&CONTTYPE = "";
&REPLYTO = "";
&SENDER = "";
&RET = SendMail(&MAIL_FLAGS, &MAIL_TO, &MAIL_CC, &MAIL_BCC, &MAIL_SUBJECT, &MAIL_TEXT,
&MAIL_FILES, &MAIL_TITLES, &MAIL_FROM, &MAIL_SEP, &CONTTYPE, &REPLYTO, &SENDER);
If &RET <> 0 Then
MessageBox(0, "", 0, 0, "Return code from SendMail=" | &RET);
End-If;

After saving SendMail code in Application Engine program, save the AppEngine with relevant name like
AE_SendMail.

Log into PIA and navigate to PeopleTools>>Process Scheduler>>Processes>>Add a new value

Add a new value as Process Type = Application Engine and Process Name = AE_SendMail. Make sure
to keep process name exactly same of the Application Engine created in AppDesginer.

In the newly created AE_SendMail process, access the Process Definition Options tab.

Under the Process Security heading, mention Component as PRCSMULTI and Process Group as
TLSALL. By selecting component as PRCSMULTI, we are assuring that this AppEngine process will
show up in Sample process requests to test.

Hit save and new AppEngine process is created.

2. Navigate to Process Scheduler>>System Process Requests and add new Run control id.
3. Click on the Run button to access the process requests page.
4. Select the newly created AE_SendMail process, its type and format and hit OK.
5. Go to Process Monitor page and view the status of process. Hit refresh to get the latest status until it comes
to Success and Posted.
6. Once the process goes to Success, you will notice that email goes to the intended user id mentioned in
&MAIL_TO flag of the SendMail code.

Please Note: By following the same steps, we can use MCFOutBoundEmail code also to send emails. From
PeopleTools 8.49.13 onwards, MCFOutBoundEmail is by default used in the notifications generated by system.
To use it through Application Engine program, follow the same process as SendMail and use the following code:
================
import PT_MCF_MAIL:*;
Local PT_MCF_MAIL:MCFOutboundEmail &eMail = create PT_MCF_MAIL:MCFOutboundEmail();

6/25/2011

PeopleTools Workflow Answer Book

/*&eMail.From = &FromAddress;
&eMail.Recipients = &ToList;
&eMail.Subject = &Subject;
&eMail.Text = &MailBody;
*/
&eMail.SetSMTPParam("mail.debug", "true");
&eMail.From = "Senders email address";
&eMail.Recipients = "Receivers email address";
&eMail.Subject = "Test for MCFOutBound";
&eMail.Text = "Test";

Local integer &resp = &eMail.Send();


Local boolean &done;

Evaluate &resp
When %ObEmail_Delivered
&done = True;
Break;

When %ObEmail_NotDelivered
&done = False;
Break;

When %ObEmail_PartiallyDelivered
&done = True;
Break;

When %ObEmail_FailedBeforeSending
&done = False;

19

Break;
End-Evaluate;

Chapter 5 Email Notifications


While many workflow-enabled applications use worklists to assign work, Workflow notifications are also used
through email. When an email notification is received, the notification typically includes a link to the PeopleSoft
page where necessary work has to be performed. Depending on business processes, may need to notify a
colleague or supervisor that work is completed.

HOW TO SEND NOTIFICATIONS

Navigate to PeopleTools>>Workflow>>Defaults & Messages>>Worklist/Email Message.

Click on the Notify button on this page

6/25/2011

PeopleTools Workflow Answer Book

Fill in the required fields as mentioned below and hit OK to send Notification:

To

Enter the user names or email addresses of those who need to take action. This field can contain
one or more email addresses or user names separated by a semicolon.

CC (carbon
copy)

Enter the names or email addresses of CC recipients, who are made publicly aware of the
notification.

BCC (blind
carbon copy)

Enter the names or email addresses of BCC recipients, who are made aware of this notification
privately.

Priority

Select a priority level for the notification: low, medium, or high. This priority is reflected in the
notification only if the %NotificationPriority variable is in the template text.

Subject

Enter the topic or a brief description of the notification. The subject value may appear by default from
a template, but you can edit it.

Template
Text

Displays the template text, which is based on a predefined notification template. The text in this field
is sent in the language of the recipient. However, the notification template has to be defined with
template text for each language.

Message

Enter your own comments. The message text is sent in the language of the sender.

Lookup
Recipient

Click to access the Lookup Address page. Enter the first characters of a recipient and click Search
to receive a list of people who match your search. To use someone as a recipient, select the check
box for the type of recipient (To ,cc, bcc) and click Add to Recipient List.

Delivery
Options

The check boxes are populated based on the delivery options that are defined in the recipient's user
profile. The Worklist check box is unavailable for external email addresses.

21

Please note that Notify button is available on almost all the pages within application. Notification can be sent from
any page but the template used from different pages is different. Templates are described later in this document.

EMAIL NOTIFICATION TEMPLATES


There are two kind of Templates used widely to send Notifications. They are:
1. Component Templates: Templates that are used for specific PeopleSoft components.
2. Generic Templates: Templates that can be used from any component.
To access and view the Notification Templates, please navigate to:
PeopleTools>>Workflow>>Notifications. Open any delivered template to have a glimpse. The important thing which
user can set in template is the Sender options.
1. Sender = User. This will send the user id who has logged in the FROM field.
2. Sender = System. This will send the user id which is mentioned in psappsrv.cfg file against SMTPSender
field.
3. Sender = Other. To use this option, need to mention the email address specifically in the space provided.
4. Sender = System-Blackberry . This is used to send notifications to Blackberry handset for approval. There is
separate setup for Blackberry integration.

SMTP GUARANTEED
There are many instances where an email cannot be sent or an email server is down. Previously we use to send an
email and if it fails there was no way to recover the same email.
Using Integration Broker, there is an advantage of retry, keeping a log of what went out and fix any issues later to
make the email go trough. Instead of sending the email server, Publish this as a message to the local gateway.

Use Message EMAIL_MSG

Use Message Channel EMAIL_CHNL

The Message Subscription peoplecode EMAIL_GUARANTEED picks up the message and try to send using
SendMail peoplecode function. Check Message Active , Default Local Node should have an Outbound Async
Transaction for EMAIL_MSG and is active , Message Channel is running , and other Email checks defined
previously

6/25/2011

PeopleTools Workflow Answer Book

Chapter 6 Backend Setup


Workflow emails are sent based on the setup at backend in Application Designer. There are delivered setups to
send and receive multiple types of Workflow Emails, Worklists and Notifications. Following are the basic identities
on which Workflow is designed and works:

BUSINESS PROCESS
1. Business Process - Workflow maps that provide a visual overview of the activities involved in a procedure.

All the blue icons shown above in Business Process are different Activities which will constitute Workflow.

ACTIVITY
2. Activity - Workflow map showing the individual steps, events, and routings that comprise a complete activity in a
business process.

23

Example shown above is of SendNote Activity which is responsible to send Worklists and Emails from
PeopleTools Workflow (As mentioned in Testing Workflow earlier).

STEPS
3. Steps are elements within activities and represent the level at which the user interacts directly with application
pages. Steps are elements within activities and represent the level at which the user interacts directly with
application pages.

Blue boxes shown above are Steps:

6/25/2011

PeopleTools Workflow Answer Book

EVENTS
4. Events represent specific transactions that can occur in the page that is connected to the event. For example,
there are several possible events on a page where managers approve orders. The manager can approve or deny
the order or send the order back to the employee for changes. Each event requires routings to inform the next
person in the chain (a buyer, an additional approver, or the employee who submitted the original order) about what
must happen next.

Yellow icon represents event:

25

Please note the Active checkbox should be checked in order to make this Activity alive.

ROUTINGS
5. Routings specify where the information goes and what form it takes: email message or worklist entry. Routings
make it possible to deploy applications throughout the enterprise. They work through the levels and departments of
an enterprise to bring together all of the roles that are necessary to complete complex tasks.

Email and Worklist icons represent Routings:

6/25/2011

PeopleTools Workflow Answer Book

Further it has attributes which defines how this will be activated and worked:

27

Worklist Record
- Used to store the Search keys for the Page

Worked By
- The next Activity in the Business Process , we considers Step 1 , Path 1 as the first step

Pooled List
- When more than one user can work on the same Worklist Item

Mark Worked When


- User Specified - Mark Worked Button in Worklist Page
- Save End User goes to the target component and save his changes
- Selected End User clicks the Worklist
- Programmatic Application developer does it using people code

Timeout Processing Active

6/25/2011

PeopleTools Workflow Answer Book


- A notification is sent out using Timeout Parameters after the worklist has been time out

Reassignable
- The user can use the Reassign button in Worklist Page

It also has the field mappings based on which this will be logged to intended user along with Subject etc:

29

Worklist Record
- This record needs to have all the search key fields required by the target component and any extra
filed for display purposes

Add Map
- Under Filed Name we see the list of fields defined in the Worklist record
- By Mapping the Application Developer is letting the PeopleSoft system know where to get values from
.The values should be available in current Component Buffer

OPRID
- Notice OPRID is not defined in the Worklist Record ? What is this
- This is the filed which decides who the user / users the worklist needs to be routed to

Record Field
- At the run time the Worklist is sent to the User in this record field
- This field when not in Level0 can result in a multiple be routed to multiple users

Constant
- Always routes to a fixed person

Role
- Resolves a list of users from the Role
- Can be a Query based Role

6/25/2011

PeopleTools Workflow Answer Book


Static Role
- This is the normal role defined using our security with a list of users

Query based Role


- These are used to get a dynamic list of users to which worklist can be routed to , the result of this
query should be a OPRID / ROLEUSER
- Can be a simple query with no bind variables
- Can be a query which has needs input using bind variables , which can be intern mapped to Record
Fields or Constants

TABLES
Worklist Table:
PSWORKLIST table stores all worklist information and linked to Worklist Record to create a worklist entry

It is import to understand what this contains in order to analyze many problems

Every worklist entry has business process , Activity , Event and Worklist Name store

INSTANCEID is Generated Uniquely for the combination

TRANSACTIONID is same as Instance ID but when the worklist is Pooled all the users who have
received a pooled worklist in the same transaction will same traction ID

OPRID is the person responsible for the worklist

ORIGINATORID is the person responsible for this worklist generation

INSTSTATUS 0 New , 1 Selected , 2 Worked , 3 Canceled

PREVOPRID is noted when the worklist is reassigned , all dates are self explanative

31

Database Definition Tables:

Application Developer

PeopleSoft System

Creates Activity

PSACTIVITYDEFN
PSBUSPROCITEM

Adds Steps into Activity

PSSTEPDEFN

Links it to a PIA Page

PSBUSPROCITEM

Adds Events

PSEVENTDEFN
PSBUSPROCITEM

Adds Worklist / Email


destination

PSBUSPROCITEM

Defines Mapping

PSMAPFIELD Contains all the field


for mapping
PSMAPRECFIELD- If Mapping using
fields
PSMAPROLENAME If Mapping
using a Role
PSMAPROLEBIND If there are
binding to Role

Define Business Process

PSBUSPROCDEFN

Add Activities

PSBUSPROCITEM

TriggerBusinessEvent
PeopleCode

The C++ runtime which actually send


a worklist or email

6/25/2011

PeopleTools Workflow Answer Book

Chapter 7 Virtual Approver

VIRTUAL APPROVER
Approval rule sets are PeopleSoft Application Designer definitions that are similar in appearance to workflow maps.
Approval rule sets reference business processes, but they are not embedded within business processes (unlike
activities, which are part of business processes). That is, approval rule sets are not represented by physical icons
on workflow maps.
Instead, approval rule sets are separate definitions that are referenced by Workflow PeopleCode. Specifically,
Virtual Approver finds the next approver by calling Virtual_Approver() and then sends that person a workflow
notification by calling VirtualRouter(). You use different PeopleCode to trigger Virtual Approver than you use for
other workflow events, but the function of the PeopleCode is the same: to identify the next users and to send them
notifications.

USING VIRTUAL APPROVER


As users complete transactions that require approvals, Virtual Approver determines the appropriate approver and
sends a workflow routing. As each approver completes the approval, Virtual Approver determines whether additional
approvals are needed and, if necessary, sends additional workflow routings.

UNDERSTANDING APPROVAL PROCESS


Approval processes are a common form of business process. The approval steps that are placed on the approval
rule set map represent the approval levels that are required for the activity.
A typical approval process incorporates many business rules, for example:

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

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

People can approve items for their own departments only.

If an item requires a vice presidents approval, bypass the usual step of manager approval.

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

33

UNDERSTANDING APPROVAL RULE SETS


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

This is a simple two step Approval rule set where approval will go in two phases:
1. Supervisor Approval:

6/25/2011

PeopleTools Workflow Answer Book

Rules setup for Supervisor to approve i.e. Monetary rules and Business Units assigned:

35

Maximum 5 Rules

Route Control - Defines the route control and mapping of the binding variable

SQL Object - Defines the SQL Object and mapping of the bind variables

And the different events based:

6/25/2011

PeopleTools Workflow Answer Book

A) On Pre-Approved

Send worklists to role-users

Worklist MUST be pooled and Mark Worked When Saved

Field map in activity should match step definition* (SQL Object)

B) On Deny

Usually send email to Originator

C) On Recycle

Usually send worklist to previous approver (parallel path)

2. Manager Approval:

37

6/25/2011

PeopleTools Workflow Answer Book

39

6/25/2011

PeopleTools Workflow Answer Book

Chapter 8 Logs & Trace Files


There are Trace and Log files specific to Application Server and Process Scheduler. Transactions are logged on the
basis of resource from which Workflow is fired.
PS: Need to enable SMTPTrace=1 and Log Fence=5 in order to capture full SMTP information in log/trace files.

APPLICATION SERVER
Application Server Log and Trace files:
1. APPSRV_MMDD.log file
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:13 SubConProcess](5) SMTP [tx]: mail from: <abc@xyz.com>
//This line shows the sender of the email
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:13 SubConProcess](5) SMTP [tx]: rcpt to: <aaa@xyz.com>
//This line shows the receiver of the email
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:14 SubConProcess](5) SMTP [tx]: Content-type: text/plain;
charset=UTF-8
// This line shows the content type like text/plain or text/html and the charset used.
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:15 SubConProcess](5) SMTP [rx]: 250 2.6.0 Message accepted for
delivery
// This line shows that the message has been accepted without any error
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:15 SubConProcess](5) SMTP [tx]: quit
// After receiving the message, SMTP server quits the connection
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:15 SubConProcess](5) SMTP [rx]: 221 2.0.0 acsmt356.xyz.com
Closing connection
// This shows that connection is closed by sender SMTP server
PSSUBHND_dflt.5764 (3) [12/01/09 16:12:15 SubConProcess](5) SMTP [ex]: close socket => Ok
// This shows that connection is fully closed.
PS: If there will be any error in delivery of email or SMTP connections, it will be listed in the logs mentioned
above.
Following is the clarification of special notations against SMTP:

SMTP [in] Making network connection

SMTP [tx] PeopleSoft sends this to Mail Server

SMTP [rx] PeopleSoft received this back from Mail Server

SMTP [ex] Closing network connection

41

3. SMTP.log
[2008-08-20 20.24.58] Mail from xxx@yyy.com to xxx@zzz.com with subject test was successful.
[2008-08-22 14.51.15] Mail from xxx@yyy.com to xxx@zzz.com with subject WF test was successful.
[2008-08-25 21.31.46] Mail from xxx@yyy.com to xxx@zzz.com with subject test was successful.
[2008-08-25 21.47.36] Mail from xxx@yyy.com to xxx@zzz.com with subject Test was successful.
[2008-08-25 21.55.43] Mail from xxx@yyy.com to xxx@zzz.com with subject Notification Test was successful.
[2008-08-26 21.22.22] Mail from xxx@yyy.com to xxx@zzz.com with subject Notification Test was not
successful.
Review APPSRV.LOG (Tracing Level 3) for further details.
PS: SMTP.log will only be initiated if there will be any Notification is involved in the transaction. It will not be
logged if transactions are done through normal PeopleTools Workflow.

PROCESS SCHEDULER
Process Scheduler log and Trace file:
1. SCHDLR_MMDD.log - Similar information is logged in Scheduler log file also as logged in Application
Server log file. The only difference here is that Workflow is initiated through Process Scheduler.
2. SMTP.log Similar information is logged as logged in Application Servers SMTP.log file.

SQL AND PEOPLECODE


SQL and Peoplecode Trace file:
1. Online Trace to capture Workflow Emails. These can be captured from login page or PeopleTools trace
options:
SQL Column 31;

SQL Statements (1)

SQL Statement Bind Variables (2)

SQL Connect, Disconnect, commit, rollback (4)

SQL Fetch (8)

SQL API (16)

PeopleCode Column 4044;

Variable assignments (4)

6/25/2011

PeopleTools Workflow Answer Book

Fetched values (8)

Program Starts (64)

External function calls (128)

Internal Function calls (256)

Function parameter values (512)

Function return values (1024)

Each statement(2048)

43

Appendix A Validation and Feedback


This section documents that real-world validation that this White Paper has received.

CUSTOMER VALIDATION
PeopleSoft is working with PeopleSoft customers to get feedback and validation on this document. Lessons
learned from these customer experiences will be posted here.

FIELD VALIDATION
PeopleSoft Consulting has provided feedback and validation on this document. Additional lessons learned from
field experience will be posted here.

6/25/2011

PeopleTools Workflow Answer Book

Appendix B Revision History


Revision History
1. 9-DEC-09: Created document.
2.

45

6/25/2011

Copyright 2006 Oracle, Inc. All rights reserved.

46

6/25/2011

PeopleTools Workflow Answer Book

PeopleTools Workflow Answer Book


December 2009
Author: Amit Jain
Contributing Authors:
Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.
Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
oracle.com
Copyright 2006, Oracle. All rights reserved.
This document is provided for information purposes only and the
contents hereof are subject to change without notice.
This document is not warranted to be error-free, nor subject to any
other warranties or conditions, whether expressed orally or implied
in law, including implied warranties and conditions of merchantability
or fitness for a particular purpose. We specifically disclaim any
liability with respect to this document and no contractual obligations
are formed either directly or indirectly by this document. This document
may not be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without our prior written permission.
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle
Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.

Copyright 2006 Oracle, Inc. All rights reserved.

47