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.

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 don’t use these functions explicitly in the Workflow PeopleCode. 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. This is the syntax:

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’ve deactivated the event, the system doesn’t run it.

This is a typical Workflow PeopleCode program:

/* 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", 
BUSEVENT."Internal Course Request");
else
         /* For external courses */
     &TEMP = TriggerBusinessEvent(BUSPROCESS."Employee Training",
BUSACTIVITY."Request Course",
BUSEVENT."External Course Request");
end-if;

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 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 routes items to the next step in the approval process.

Using the GetApprovers Library Function

The GetApprovers function isn't a regular PeopleCode function. It's a library function, like Virtual Approver. It's 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 GenerateActGuideContentUrl, GenerateActGuidePortalUrl, GenerateActGuideRelativeUrl.

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 current item’s worklist record. This is the syntax:

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 didn’t open this page from a worklist, some variables are blank.

See System Variables.