Defining Event Triggers

This chapter provides an overview of event triggers and discusses how to:

• Write Workflow PeopleCode.

• Write PeopleCode for approval processes.

• Use additional PeopleCode functions and variables.

Understanding Event Triggers

As you define workflow processes, you identify the application pages that trigger business events. Then you must add PeopleCode programs to the pages so that they actually trigger the events. The PeopleCode detects when a business rule has been triggered and determines the appropriate action.

Writing Workflow PeopleCode

This section provides an overview of Workflow PeopleCode and discusses how to:

• Use the TriggerBusinessEvent function.

• Create Workflow PeopleCode programs.

• Clone business processes and activities.

Understanding Workflow PeopleCode

To trigger a business event from a page, you add a PeopleCode program to the workflow event in the record definition for one of the tables to which the page writes. For example, to trigger events from the Course Request page, add Workflow PeopleCode to the TRAINING record definition; TRAINING is the record definition with which the Course Request page fields are associated.

If you’re triggering business events from a page that includes scrolls, add the Workflow PeopleCode to the record definition at the appropriate scroll level. If, for example, you add it to the record definition that is associated with a level one scroll area, the PeopleCode runs once for each row at that level. A Workflow PeopleCode program can reference record fields from record definitions at the same scroll level or at a lower scroll level. These rules also apply to the SaveEdit PeopleCode for Virtual Approver.

Workflow PeopleCode runs after the user saves the page group and before it updates the database with the saved data. More specifically, it runs after SavePreChange PeopleCode and before SavePostChange PeopleCode. Because SavePostChange PeopleCode runs after Workflow PeopleCode, it does not run if the Workflow PeopleCode fails to finish.

Workflow PeopleCode programs typically review the data in the saved record, then decide which business event to trigger, if any. They all include at least one use of the PeopleCode function that triggers events, or Virtual_Router, a PeopleCode library function that is associated with Virtual Approver, which uses TriggerBusinessEvent internally. The Virtual_Router PeopleCode library function is located in the FieldFormula event of the APPR_VA0_WRK.FUNCLIB_02 record field.

You can add the Workflow PeopleCode to any field in the record definition. For clarity, you can add it to a field that the program itself references. For example, you might add the Workflow PeopleCode that triggers an approval process to the Approval Status field.

Using the TriggerBusinessEvent Function

You use this function in every Workflow PeopleCode program.

In components that use Virtual Approver, you do not use these functions explicitly in the Workflow PeopleCode. Instead, you use the Virtual_Router PeopleCode library function, which uses these two functions internally.

TriggerBusinessEvent triggers a specified business event and the workflow routings that are associated with that event. The syntax is:

TriggerBusinessEvent(BUSPROCESS.BusProcName, ​BUSACTIVITY.ActivityName, ​BUSEVENT.⇒
BusEventName)

The BusProcName, ActivityName, and BusEventName parameters are the names of the business process, activity, and event from PeopleSoft Application Designer. They are all strings, enclosed in quotes. For example, the following code triggers the Deny Purchase Request event in the Manager Approval activity of the Purchase Requisition business process:

TriggerBusinessEvent(BUSPROCESS."Purchase Requisition", BUSACTIVITY."Manager⇒
 Approval", BUSEVENT."Deny Purchase Request")

See TriggerBusinessEvent.

Creating Workflow PeopleCode Programs

Do not use this section for components with Virtual Approver.

The general structure of all Workflow PeopleCode programs is the same:

• Check for the condition under which a business event should be triggered.

  This condition is a business rule.

• If the condition is true, trigger the event.

  The system automatically determines whether the event is active and, if so, triggers it. If you have deactivated the event, the system does not run it.

A typical Workflow PeopleCode program looks like this:

/* Start the Employee Training process for a new course request */
                
if RecordNew(ATTENDANCE) then
                
     if COURSE_TBL.INTERNAL_EXTERNAL = "I" then
                
          /* For internal courses */
                
          &TEMP = TriggerBusinessEvent(BUSPROCESS."Employee Training",⇒
         BUSACTIVITY."Request Course",BUSACTIVITY."Request Course", ⇒
         BUSEVENT."Internal Course Request");
                
     else
                
         /* For external courses */
                
         &TEMP = TriggerBusinessEvent(BUSPROCESS."Employee Training",⇒
        BUSACTIVITY."Request Course",BUSEVENT."External Course Request");
                
      end-if;

Cloning Business Processes and Activities

There may be instances when you want to share business processes and activities across applications or portals. This sharing can lead to instance ID overlap in applications, making it difficult to identify different transactions with the same business process name.

Using the CloneBusProc library function, you can clone the business process by providing a new name. This function clones all associated activities, steps, and events for the business process with the new prefix.

Syntax

CloneBusProc(&old_name, &new_name, &prefixname)

Parameters

Example

This example code will clone the business process EOAW_APPROVALS, the cloned business process name will be EPRO_APPROVALS. The associated activities, steps and events will contain NEW_ as a prefix to the existing name.

Declare Function CloneBusProc Peoplecode WF_FUNCLIB_WRK.BUSPROCNAME FieldFormula;

Local string &oldname;
Local string &newname;
Local string &prefixname;
&oldname = "EOAW_APPROVALS";
&newname = "EPRO_APPROVALS";
&prefixname = "NEW_";
&bReturn =  CloneBusProc(&oldname, &newname, &prefixname);

Writing PeopleCode for Approval Processes

This section provides an overview of approval processes and discusses how to:

• Use virtual approver.

• Use the GetApprovers library function

Understanding Approval Processes

Approval processes are a common form of business process. PeopleSoft has simplified the process of defining approval processes by enabling you to define approval rules on an approval rule setmap. You can then choose a tool to read and implement the approval rules from the map.

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.

To trigger Virtual Approver from a page, use two PeopleCode functions in the record definition that is associated with the page:

• Use the Virtual_Approver function in the SaveEdit PeopleCode.

  This function checks the approval rules that you defined in the approval rules sets and determines whether an item must be routed for approval.

• Use the Virtual_Router function in the Workflow PeopleCode.

  This function routes items to the next step in the approval process.

Using the GetApprovers Library Function

The GetApprovers function is not a regular PeopleCode function; it is a library function, like Virtual Approver. It is located in the FieldFormula event of the APPR_VA0_WRK.APPR_RULE_SET record field.

The GetApprovers PeopleCode function checks an approval rules set and determines the entire list of required approvals at once, so that you can develop custom approval tracking applications.

Using Additional PeopleCode Functions and Variables

You might find the following Workflow PeopleCode functions and variables useful as you begin more advanced workflow development.

GenerateActGuideContentURL, GenerateActGuidePortalURL, GenerateActGuideRelativeURL

These functions generate different types of URLs to the specified activity guide (life event). Generally these functions are used in iScripts for populating application pages that you are generating on your own with HTML.

See The Generate Functions.

GetWLFieldValue

When you open a page from a worklist (by selecting one of the work items), this function enables you to get the value from one of the fields in the worklist record of the current item. The syntax is:

GetWLFieldValue(field_name)

The field_name parameter specifies the field from which you want the data. It must be a field from the worklist record definition.

See GetWLFieldValue.

MarkWLItemWorked

When you open a page from a worklist (by selecting one of the work items), this function marks the current worklist entry as worked. MarkWLItemWorked takes no parameters and can be used only in Workflow PeopleCode.

See MarkWLItemWorked.

System Variables

You might want to use these system variables during workflow development. If you did not open this page from a worklist, some variables are blank.

See System Variables.