Adding Events and Routings

This chapter provides an overview of events and routings and discusses how to:

• Add and define events

• Add and define worklist routings.

Understanding Events and Routings

This section lists common elements and provides an overview of events and routings.

Common Elements Used in This Chapter

Events and Routings

When you create a business process in PeopleSoft Application Designer, you specify which activities form a business process and in what order they must be completed. The map provides an overview of the process, but it doesn’t provide a link between the activities. To link the activities to a workflow, you add routings, which automate the delivery of information to other activities and other users.

Events are conditions that have associated routings. Define the condition in PeopleCode, which is attached to the record definition underlying a step in a step map. When a user saves the page, completing the step, the system runs the PeopleCode program to test the condition. If the condition is met, the system performs the routings.

Routings can deliver data in two forms: worklist entries and email messages. To create a routing, specify the routing type, who should receive the data, and which data you want to send. The data is usually a subset of the data from the step that triggers the routing.

Adding and Defining Events

Add and define events in PeopleSoft Application Designer.

This section discusses how to:

• Add an event

• Define the event

• Edit the business rules

Adding an Event

To add an event:

1. Open the activity to which you want to add the event.

2. Click the Event button in the toolbar.

3. Click where you want the event to appear on the map.

   The Event icon appears on the map.

4. Connect the Event icon to the icon for the step that triggers it.

   1. Click the Connector icon in the palette.

   2. Click the Step icon, then the Event icon.

      An arrow connects the two icons.

      Use the Link icon, not the Line icon, to connect an event to the step that triggers it. If you use the Line icon, the system won’t recognize the event.

Defining the Event

To define the event:

1. Double-click the Event icon, or right-click and select Item Properties.

   The Event Definition dialog box appears.

2. Enter a name and description of the event.

   Name	Enter the name used to trigger the event with the TriggerBusinessEvent PeopleCode function. By default, the event name also appears as the display text under the icon on the map.
   Active	When an activity triggers an event, the TriggerBusinessEvent function determines whether the event is active. To temporarily deactivate an event, preventing any of its routings, clear this check box. To restart an inactive event, select it.
   Event Triggered from Record Name	Select the record definition to which you want to add Workflow PeopleCode to trigger the business event.

Editing the Business Rules

To edit the business rules:

1. Click the Edit Business Rules button.

   The PeopleCode Editor appears. The name of the first key field in the specified record definition appears in the title bar.

   Note. The Edit Business Rules button adds the Workflow PeopleCode to the first key field in the specified record definition. If you use Virtual Approver, use PeopleSoft Application Designer to add SaveEdit PeopleCode to this same record.

2. Enter the PeopleCode that triggers the business event.

3. Save the PeopleCode.

4. Click OK to close the Event Definition dialog box.

Adding and Defining Worklist Routings

This section discusses prerequisites to defining worklist routings and discusses how to:

• Create worklist routings.

• Define worklist attributes.

• Specify field mappings.

Prerequisites to Adding and Defining Worklist Routings

Before you create a worklist routing for an activity, create a worklist record definition. The worklist record determines what fields the system stores for each work item.

See Creating Worklist Record Definitions.

Creating Worklist Routings

To create a worklist routing:

1. Create the business event that triggers the worklist routing.

2. Click the Worklist button on the toolbar.

3. Click where you want the Worklist icon to appear on the map.

   The Worklist icon appears.

4. Connect the worklist routing to the event that triggers it.

   1. Click the Connector icon in the palette.

   2. Click the Event icon, then the Worklist icon.

      An arrow connects the two icons. Use the Link icon to connect a routing to an event. If you use the Line icon, the system won’t recognize the routing.

5. Double-click the Worklist icon, or right-click and select Item Properties.

   The Worklist Definition dialog box appears.

6. Enter a name and description for the worklist routing.

Defining Worklist Attributes

Define worklist attributes on the Worklist Attributes dialog box.

To define worklist attributes:

1. On the Worklist Definition dialog box, click Attributes.

   The Worklist Attributes dialog box appears.

2. Select the worklist record, business process, and activity from the appropriate drop-down list boxes.

   Worklist Record	Select the record definition to use for storing and displaying work items.
   Business Process	Enter the business process name that is associated with the worklist item.
   Activity	Enter the activity name that is associated with the worklist item. When a user selects a work item from the worklist, the system displays the page (or external program) that is associated with the first step in the activity that you specify here. The first step is the one marked as Step 1 Path 1 in the step map. You usually select the next activity in the current business process, but this is not required. You can route to any activity in any business process. This is the “Worked by” business process and activity, which may not be the same as the business process or activity that triggered the worklist.

3. Select worklist page attributes.

   Show Instances, Allow Multiple Unworked,and Worklist Acts Like Prompt List	Reserved for future use.
   Pooled List	Specifies whether the system creates a single shared work item or one work item for each worklist user. With a pooled worklist, all worklist users receive copies of shared work items; the first user who selects an item works on it, and the item is dropped from everyone else’s worklist. With a non-pooled worklist, each user receives a personal copy of each item. If Delete Pooled WL When Select is selected on the Worklist System Defaults page, a pooled worklist will be deleted from other queues when a user selects it.
   Timeout Processing Active	Specifies whether the system checks this worklist for overdue items.
   Reassignable	Enables users to reassign worklist items to other users.

4. Specify the timeout parameters (if timeout processing is active).

   Timeout Parameters	Specifying a timeout condition is optional. If you want all work items to remain in this worklist until a user processes them, leave the controls in this group box blank, or clear the Timeout Process Active check box. Otherwise, specify how long to wait (days, hours, and minutes) for a user to process a work item. The system adds the three values together. If a work item sits in the worklist for longer than the specified amount of time, the system performs the action identified by the check box that you select.
   Email Assigned Current User	Send an email message to the user to whom the work item is assigned, warning that the item is overdue.
   Email Supervisor	Send an email message to the user’s supervisor. The supervisor is assigned as the user’s supervising role user in the user profile, maintained through PeopleSoft Security. In PeopleSoft HRMS applications, the system uses the supervisor from the user’s PERSONAL_DATA record.
   Send Timeout Worklist	Send a new worklist item to the currently assigned user’s timeout worklist.

5. Specify what the user must do before the system considers a work item to be worked.

   Work items remain in a user’s worklist until they have been worked.

   User Specified	A work item is marked as worked when the user explicitly identifies it as worked by selecting it on the Select Worklist page and clicking the Mark Worked button. This option is useful when the user must return to the same work item several times or wait for supporting information. If the worklist item is replicated from another database, the Mark Worked function is disabled in the target database.
   Saved	A work item is marked as worked when the user saves work on the page that is assigned to the worklist. This option is appropriate for work items that the user can complete right away.
   Selected	A work item is marked as worked as soon as the user selects it from the worklist. This option is appropriate for work items that notify the user of an event; just seeing the item is sufficient.
   Programmatic	A work item is never marked worked directly by the user. It can be marked as worked only with PeopleCode. This setting enables you to provide additional logic to determine when a work item can be considered worked.

6. Click OK to close the Worklist Attributes dialog box and return to the Worklist Properties dialog box.

Specifying Field Mappings

Specify field mappings on the Field Map dialog box.

To specify field mappings:

1. Click the Field Mapping button.

   If the Field Mapping button is unavailable, you haven’t properly linked the routing to the event that triggers it.

   The Field Map dialog box appears. Use this dialog box to tell the system where to find the data to create a worklist entry. The Message Map group box lists the fields involved.

   Name	Displays the user ID (OPERID) of the person who receives the worklist routing. It may also display the fields in the worklist record, which includes key data for the page where the user performs the necessary work and the descriptive data that appears in the user’s worklist—normally the WORKLIST_URL and WORKLIST_DESCR fields.
   Mode	Specify the map mode value from Copy, Xlat-S, or Xlat-L (use one of these two values if the field has a translate table value).
   Value	Indicates where the system finds the data to enter into those fields.

2. Select the field to which you want to map a value.

3. Click the Change button, or to add a new field to the map, click the Add button.

4. The Map Field dialog box appears. Use this dialog box to provide a value for each field in the worklist record.

5. Select the field into which you want to place routing data.

   If you select the field from the message map, its name appears in the Field list box. If the correct name doesn’t appear, you can select a field from the list box or enter a new name.

6. Identify the value for the selected field.

   There are three ways to put data into a field: from a database field, a specific constant value, or a role name.

   Record Field Value	To enter the value from a database field into the worklist field, select the RecField option. The Record box lists the record definitions that should be available when the event triggers this routing (according to the page and record definition associated with the event). Select the record name. The fields in that record appear in the Fields list box. Select the field whose value you want. When the event is triggered, the system completes the worklist field with the value of the field in the current record.
   Constant	To assign a specific constant value to the field, select this option and enter the value in the text box to the right. Every worklist entry will have this value in the selected field.
   Role Name	To assign a role name to the field, select this option and select a role from the drop-down list box that appears next to it. When the event is triggered, the system completes the field with a list of users who fill this role. If you select a user list role, each user who is assigned to that role receives a copy of the work item. If you select a query role, each user that the query returns receives a copy.

7. If you map the field to a role name, provide values for any bind variables.

   If you map the user ID field to a query role that includes bind variables, the Specify Query Bind Variables button appears next to the Role Name option. When you click this button, a dialog box appears, enabling you to specify the value that each bind variable in the query should take for each work item.

   The Query Bind Variable column displays the bind variables for the role query. (If nothing appears in this column, you defined the query without specifying any bind variables.) The Record column lists the record definitions associated with the component that triggers this routing. The Field column displays the fields in the selected record definition.

   You can bind each variable with the value from a record field or with a constant:

   • To bind a variable with the value from a record field, select the Field option, select the bind variable for which you want to provide a value, and select the record field to contain the value.

   • To bind a variable with a constant, select the Constant option, and enter the value into the text box.

8. When you’ve mapped bind values for all of the variables, click OK to close the dialog box.

   Note. If you’re using route controls with Virtual Approver, the role that you assign to the OPRID field is one of the predefined route control query roles.

9. If you map the field to a record field, specify whether the system copies the assigned value directly into the worklist field or replaces the assigned value with a value from the translate table.

   Select the appropriate option from the Map Mode list box. This list box is available only if the selected field has associated translate table values. In most cases, leave the default value (Copy).

   For example, suppose the worklist record definition includes an Employment Status field, and you associate the field with the record field PERSONAL_DATA.STATUS. If the PERSONAL_DATA.STATUS field holds an abbreviation that translates to a value in the translate table, you can tell the system to populate the worklist field with the abbreviation (Copy) or with the corresponding translate table value (Xlat-S for the short form or Xlat-L for the long form).

10. Click OK to add the field and its value to the routing dialog box.

11. Repeat steps 5 to 10 for each field that you want to add to the worklist routing.

    You must provide values for all of the key fields in the worklist record definition.

12. Close all of the dialog boxes by clicking OK in each one.

Adding and Defining Email Routings

This section provides an overview of email routings and discusses how to:

• Create an email routing.

• Map fields.

Understanding Email Routings

With email routings, you can send email messages in response to business events. In some cases, you might want to define two routings for the same event: one that adds an item to someone’s worklist and one that sends an email message to tell that person about the new worklist item.

You can send an email routing to anyone to whom you can send email messages through the mail system. PeopleSoft applications support email routings to any email software that supports the Simple Mail Transfer Protocol (SMTP) standards.

Creating an Email Routing

To create an email routing:

1. Create the business event that triggers the email routing.

2. Click the Email button on the toolbar.

3. Click where you want the Email icon to appear on the map.

   The Email icon appears.

4. Connect the email routing to the event that triggers it.

   1. Click the Connector button in the palette.

   2. Click the Event icon, then the Email icon.

      An arrow connects the two icons.

5. Use the Link icon to connect a routing to an event.

   If you use the Line icon, the system won’t recognize the routing.

6. Double-click the Email icon, or right-click and select Item Properties.

   The Email Definition dialog box appears.

7. Enter a name and description for the routing. By default, the routing name also appears as the display text under the icon on the map.

8. Select any settings to apply to the email message.

   The options in this dialog box correspond to the mailing options offered in most email software. If your email software does not support one or more of these options, the system ignores its setting.

   See See the documentation for your email software.

9. Click to return to the Email Definition dialog box.

Note. When designing workflow, consider the following behaviors of email routing:

Calling TriggerBusinessEvent PeopleCode in workflow is part of process of saving, so any failure of TriggerBusinessEvent results in a failure to save. If there is an email route and email failed then the save process will fail and the database transaction will roll back. However, if TriggerBusinessEvent has successfully sent the email but the saving process failed after the workflow event, the sent email cannot be rolled back.

Mapping Fields

Map fields for your email routing on the Field Map dialog box.

To map fields:

1. Select Field Mapping .

2. The Field Map dialog box appears.

   Use this dialog box to tell the system where to find the data to create an email message. The Message Map group box lists the fields involved.

   Name	Displays the fields.
   Value	Indicates where the system finds the data to enter in the fields.

   The fields that appear in this dialog box represent the two different types of data that are needed to create an email message: who and what. That is:

   • Who receives the email message?

     The TO field holds the email address for this person.

   • What is the content of the email message?

     This includes a SUBJECT line and any additional text that you add. You can also concatenate data into the message. When you first open the dialog box, the Name column displays the fields available for mapping. You must provide a value for the TO field.

3. Select the field into which you want to map a value.

4. Click the Change button, or to add a new field to the map, click Add.

5. The Map Field dialog box appears.

   Use this dialog box to create the email message from the values provided by the step that triggers the routing.

6. Select the field into which you want to place routing data.

   If you select the field from the message map, its name appears in the Field list box. If the correct name doesn’t appear, you can select a field from the list box or enter a new name.

   The following fields in an email routing’s message map have specific meanings to the email software to which the system forwards the email message.

   TO	Indicates the name of the person to whom you want to send the email message. The value can be an email name or a role. To send to more than one person, separate the names with semicolons. The values in the TO, CC, and BCC fields determine who receives the email message. The values that you map to these fields can be email addresses, role user IDs, or role names. The system automatically converts role user IDs and role names into the users’ email addresses.
   FROM	(Optional) Indicates the email address of the sender. Setting this value overrides the system SMTPSender value so that the recipient of the email message can reply to an individual, rather than to the system email address.
   REPLYTO	(Optional) Indicates the email address to which the sender recommends sending replies.
   SENDER	(Optional) Indicates the email address of the actual originator of the email if different from the address set in the FROM field.
   CC and BCC	(Optional) Indicates the names of other people to whom you want to send the message.
   SUBJECT	Indicates the subject line that appears in the receiver’s email inbox.
   NOTETEXT	Indicates the body of the message. The message can have multiple NOTETEXT fields. The system displays NOTETEXT fields in the order in which they appear in the Field Map dialog box.

   Note. When the PeopleSoft system constructs an email address to be used in email notifications, the system does so according to the following conditions: If the system detects an email address with a value enclosed in angle brackets, as in <email_address>, the system uses that enclosed value. If the system does not detect angle brackets in the email address, the system encloses the entire email value in angle brackets when transmitting the email message.

7. To add a new NOTETEXT line, click the Add button in the Field Map dialog box.

8. Select NOTETEXT in the Field Name box.

   FILEPATH	(Optional) Indicates the completed qualified path and filename for a file to attach to the email message.
   FILENAME	(Optional) Indicates the name to display in the body of the email message, below the icon that represents the file attachment.
   FILETYPE	(Optional) Indicates the type of file being attached.

9. Identify the value for the selected field.

   The value can be data from a record field, a specific constant value, or a role name.

   Record Field Value	To enter the value from a record field into the email message, select the RecField option. The Record box lists the record definitions that should be available when the event triggers this routing (according to the page and record definition associated with the event). Select the record name. The fields in that record appear in the Fields list box. Select the field whose value you want. When the event is triggered, the system completes the email field with the value of the record field in the current record.
   Constant	To assign a specific constant value to the field, select this option and enter the value in the text box to the right. Every email message will have this value in the selected field.
   Role Name	To assign a role name to the field, select this option and select a role from the drop-down list box that appears next to it. When the event is triggered, the system completes the field with a list of users who fill this role. If you select a user list role, each user who is assigned to that role receives a copy of the email message. If you select a query role, each user that the query returns receives a copy. Although the role returns a list of role users, the system enters the user’s email address into the field. There must be an email address in each role user record.

10. If you map the field to a role name, provide values for any bind variables.

    If you map the TO, CC, or BCC field to a query role that includes bind variables, the Specify Query Bind Variables button appears next to the Role Name option. When you click this button, a dialog box appears, enabling you to specify the value that each bind variable in the query should take.

    The Query Bind Variable column displays the bind variables for the role query. (If nothing appears in this column, you defined the query without specifying any bind variables.) The Record column lists the record definitions associated with the component that triggers this routing. The Field column displays the fields in the selected record definition.

    You can bind each variable with the value from a record field or with a constant:

    • To bind a variable with the value from a record field, select the Field option, select the bind variable for which you want to provide a value, and select the record field that will contain the value.

    • To bind a variable with a constant, select the Constant option, and enter the value into the text box.

      When you’ve mapped bind values for all the variables, click OK to close the dialog box.

      Note. If you’re using route controls with Virtual Approver, the role that you assign to the TO field is one of the predefined route control query roles, and the bind variable values come from a work record that you need to add to the component that’s triggering the routing.

11. If you map the field to a record field, specify whether the system copies the assigned value directly into the field or replaces the assigned value with a value from the translate table.

    Select the appropriate option from the Map Modedrop-down list box. This list is available only if the selected field has associated translate table values. In most cases, leave the default value (Copy).

    For example, suppose that you want to include a person’s employment status in the email message, so you associate the NOTETEXT field with the record field PERSONAL_DATA.STATUS. If the PERSONAL_DATA. STATUS field holds an abbreviation that translates to a value in the translate table, you can tell the system to populate the field with the abbreviation (Copy) or with the corresponding translate table value (Xlat-S for the short form or Xlat-L for the long form).

12. Click OK to add the field and its value to the routing dialog box.

13. Repeat steps for each field that you want to add to the routing.

14. Close all of the dialog boxes by clicking OK in each one.