HCM 9x TL Templates Made Available White Paper Final

Templates Made Available – Creating Rule Templates

An Oracle White Paper

May 2011



Disclaimer

The following is intended to outline our general product direction. It is intended for information

purposes only, and may not be incorporated into any contract. It is not a commitment to deliver

any material, code, or functionality, and should not be relied upon in making purchasing

decisions. The development, release, and timing of any features or functionality described for

Oracle’s products remains at the sole discretion of Oracle.


Executive Overview .................................................................................. 1

Introduction .............................................................................................. 1

Pre-Requisites .......................................................................................... 5

Create / Select Rule Objects................................................................. 5

Create / Select Presentation Page ........................................................ 5

Create / Select an Explanation Message .............................................. 6

Create / Select a Derived Record (Parameter Holder) .......................... 6

Defining a New Template ......................................................................... 7

Define Header Page Controls ............................................................... 7

Define Detail Page Controls ................................................................. 9

Define Text (Rule Explanation) Parameters ........................................ 10

Template Controlling Code ................................................................. 11

Define Template Rule Steps ............................................................... 12

Define Template Step Parameters ...................................................... 13

Identify and Develop App Class Logic - “Optional” .............................. 16

Packaging........................................................................................... 18

When Do I Need Template Controlling Code .......................................... 19

Rule Text [TEMPLATE060] ................................................................ 19

Presentation [TEMPLATE160] ............................................................ 20

Validation [TEMPLATE300] ................................................................ 21

Building Rule [TEMPLATE090] ........................................................... 22

Create Templates Using the new Generic Entry Pages .......................... 24

Set Up the Pre-Requisites .................................................................. 24

Create the Template ........................................................................... 26

Test-drive the Template ...................................................................... 28

Things We Worry About ......................................................................... 32

Performance, Performance, Performance .......................................... 32

Conclusion ............................................................................................. 32


1

Executive Overview

The time processing portion of Time and Labor – called Time Administration – is a rules

engine. A rules engine is only as good as its rules, and – equally important – its ability and

flexibility in terms of creating and maintaining those rules. While our application enables

users to build custom, or non-template-based, rules, customers continually request that we

deliver more templates. By tweaking the template architecture and offering a PeopleSoft

Internet Architecture (PIA) interface for maintaining the template definition we can greatly

improve our customers’ ability to configure and maintain a much wider and flexible set of

rules that cater to their needs.

Introduction

Time and Labor has many different rules, but when we talk about Time and Labor Rules and

the Rules Engine we are referring to the rules that act on the raw scheduled or reported time

and convert it into the correct payable time for a time reporter.

Some reporters may be paid overtime and their time is subject to rules that convert anything

they report above 8 hours on a given day to overtime, which is paid at 1.5x the regular rate.

Other rules may create exceptions that prevent the automatic conversion of certain reported

time to payable time. There may be limits to allowed worker’s meal allowances, and if they

report more, we cap the amount, issue an exception to alert the manager, and prevent the

excess amount from being paid out.

In technical terms a rule is an AE (Application Engine) section with a series of SQL

statements that are executed in a defined order to produce the desired outcome -- payable

time or exceptions.

The template-based approach enables the creation of new rules in a vastly simplified and

functionally reasonable manner.


2

Interface for defining Template-Based Rules

The underlying rule template defines the set of SQL statements that are required to enact a

particular type of rule. The original template is very similar to a rule, except the SQL objects

contain pre-defined slots where the parameterized values can be inserted.

In its enhanced version, the template also defines and controls the UI (User Interface)

where end-users - who may not have extensive rule-building skills - can input the functional

criteria that make up the rule. This is part of the main Template Definition.

The template continues to list the rule steps and the SQL objects upon which the

parameters entered by the user are applied to generate the executable code specific to

each rule. The new template also defines how the information – parameters - from the UI

fits into the template’s explanation and the template’s executable steps, or SQL objects.

Defining Template Rule Steps – Underlying table is old, the interface is new.


3

SQL objects subject to customization have placeholders – recognized as %RuleTemplate()

– that are replaced with rule specific information to create the executable AE section and its

SQL steps:

Generic Template Object and a matching Sample Executable - Example

There is a business need for a UI that enables the maintenance of existing templates and

offers the ability to create new templates.

This proposed change suggests the following:

• The introduction of an interface (PIA) for creating and maintaining template definitions.

This allows the user a mental picture of what is being built, and enables validations of

the data entered.

• Elimination, or a drastic reduction, of template-specific PeopleCode. While some

templates are so specific or complicated that they do not fit a generic mold, the current

design has enabled removing template-specific logic from 41 of the 53 delivered

templates.


4

• Full isolation of any template-specific PeopleCode. Meaning that customers can host

code that is linked to customer-created templates in dedicated APIs, which isolates

them from PeopleSoft delivered updates.


5

Pre-Requisites

Prior to creating your template you need the following components.

Create / Select Rule Objects

Most working steps in a template require a SQL Object or an Action just like a basic rule. We typically name template-serving objects for the template they support – such as TMPL030_U10. Common utility steps are named TMPL000_XYZ. Creating rule objects is a separate discipline within T&L that is beyond the scope of this paper. Suffice it to note that the %RuleTemplate() placeholder is an integral part of template-based rules because it represents pointers to where the rule-specific information given by the rule creator fits into the generated SQL statements.

Create / Select Presentation Page

This is the page used to present the detail parameters specific to your rule from the Template-Built Rules component. For Oracle delivered templates there are a number of pages available on the TL_TA_RULE_TMPLT component that may cater to the parameters required for your new template.

Component contains many pages – only one is selected for display based on template setting.

Two new generic pages, TL_TEMPLATE_GEN and TL_TEMPLATE_GRID, provide more options for those who are reluctant to modify the delivered component object.


6

Create / Select an Explanation Message

Select or create the message catalog entry as a template for the rule explanation. The message catalog entries for Oracle delivered templates all go in the 13507 message set.

Sample Explanation

The messages typically contain placeholders where rule-specific parameters are entered for each new rule. Each placeholder starts with (n) – where n is the placeholder number and contains an uninterrupted text string that is intended to guide the user in the process of creating the new rule. A space, a period, a comma or a semi-colon are all recognized as characters that define the end of the placeholder text.

Create / Select a Derived Record (Parameter Holder)

Oracle delivered templates use the record DERIVED_TL_TMPL as a rule, which probably contains fields that are suited for your template needs. For custom (customer-specific) development you should create your own record and place all parameters linked to a given template on the same record. This is not technically required, it just seems easier to maintain and manage.


7

Defining a New Template

After adding or selecting your page on the TL_TA_RULE_TMPLT component, adding your rule explanation message and adding or identifying the necessary rule objects, you are ready to define your template.

The New Main Template Definition

Template ID and Core Component: Templates that are delivered as part of the product must use the reserved prefix TEMPLATE. Delivered templates, like other T&L rule objects, are marked as Core Components. Once marked, the UI presents the template in display-only mode. Selecting a Template Type filters the search results returned when the user accesses the template built rules component. The Template Type field was designed to divide templates and rules into types. You will likely find one existing “type” that contains rules that are similar to the one you are about to create. Explanation: Rule Templates are very specific to our product and probably not representative of how the end-user thinks of their functional area. The definitions are set up with this field to allow for helpful descriptions. Use it!

Define Header Page Controls


8

Header Page Controls

The header page region controls three fields or areas on the Template Header page.1

Header Page and the Objects being controlled

Time selection controls punch types that are available and also whether a selection is required. There are a variety of options including “Controlled By Code,” which is used when the list of what is enabled, what is defaulted and what is required becomes overly complicated. Only a few of the existing templates fall in this category. Controlled by Code is discussed later in this document. Profile Selection applies to rules that add new IPT (Intermediate Payable Time) in addition to the existing entries and therefore needs to fill in the task information on the

1 To fully understand the effect of the different Time Selections and Period Filters, you should review the existing templates and rules and observe how the Template Header page behaves for templates that use the different settings.


9

new row. This setting is irrelevant for rules that generate exceptions or merely alter content on already existing rows. Period Filter controls which calendars the user can select in the Period ID field of the Template Header page. For example, it makes little sense to allow the entry of a weekly calendar for the daily threshold rule. For a few templates the calendar is not applicable – in which case you select the TL_PERIOD_NA_VW.

Delivered Period Filtering Views

You may need to add a new view to limit the selection of calendars for the rules using your template. The tactic devised to limit the prompt view to relevant record definitions is to set TL_TIME_PERIODS as the parent record on the view definition:

If you add a new filtering view make sure that you also provide the related language view.

Define Detail Page Controls

Detail Page Controls


10

Detail Page: Specify the page you want displayed. In chapter 5 we will review the new generic pages, TL_TEMPLATE_GEN and TL_TEMPLATE_GRID, which support custom template development. List Type: This is an optional field that indicates the list of values, if a list is used, from which the user selects. No template so far has utilized more than one List Field. Action: Only a few of the existing templates require specification of whether to replace (modify) the incoming reported time or add an extra entry of IPT. The Action field controls the default setting for this parameter.

Detail Page and Objects being controlled

Define Text (Rule Explanation) Parameters

When you specify a Rule Explanation message, you need to point to the right parameter for each placeholder in the template message.


11

Template Text Parameters Page

In a few cases the user is allowed to enter a single TRC using the TRC field, or a list of TRCs using the LIST_ID field. In that case, enter TRC as a Field Name and as the List Type for that parameter. This information is stored in the new TL_TMPLT_PARMT table.

Template Controlling Code

Template Controlling Code

The old architecture used events such as page-activate and save-edit as well as the TL_BUILD_TEMPLATE application class to control the display, validate rules, and then generate rules from the template-built rules component. With the new architecture you should not need to write code specific to your template. A number of templates exist with examples to illustrate this. Chapters 3.6 and 4 are dedicated to this topic.


12

Making this configurable allows customers to create separate app classes that isolate their custom code away from delivered code and the concern regarding future upgrades. Root Package ID: This field indicates the name of the application package. This should be set to TL_RULETEMPLATES for all delivered templates. For this (root) package, the default package name is PSFT, and as a developer you need to add your logic into an application class under the PSFT package:

Snapshot of the Oracle-delivered App Class Library

For custom packages the Package Name is optional and the application class can be placed directly under the root package. The only requirement we have is that the package name is identical to the template ID.

Define Template Rule Steps

This portion of the template is taken from the original design. The template steps define the rule logic.

Template Rule Steps Definition page


13

AE Action: This is a new field in this region. Previously, the system only supported single SQL action steps. Now the system provides a little more flexibility in terms of creating rules. All of the available selections in this field should be recognizable from AE program development, except for SQL – Quit if No Rows. This option produces a SQL step with attributes that skip the remaining steps in the rule section unless this statement produced or returned any rows. This should be useful in terms of performance. Statement Type: There are four available statement types. A typical rule truncates, or deletes the content of its work tables, and then defines the actual rule logic by copying relevant information into its work tables. There may be intermediate steps that update the statistics on these tables for better performance. For actual logic, the system supports both Actions and SQL Objects, but Action rule objects are not currently deployed by any template rule. Specifying the steps should be straight forward: • Number the steps in the order they are to be executed. • Indicate the Action type. • Indicate the Statement Type and the related object; the table to truncate or update

statistics on or the SQL Object or Action to run for those types of steps. • The interface has a link that enables you to edit or review the SQL object or Action. • The interface automatically detects the number of parameters required by the rule

object and updates the template step. • For each statement that requires parameters – remember %RuleTemplate() – a link

is enabled to specify the parameter mapping, as we did for the rule explanation text.

Define Template Step Parameters

The interface behind the parameters link enables the parameter mapping while displaying the template SQL for guidance:


14

Template Step Parameters Page with Generic Rule Expression

There are additional items that were not an issue on the rule text parameter page:

Template Step Parameters Page

Required Field: In addition to identifying the order and the source field, you need to indicate whether the field is required. This is the default setting, but sometimes you may want to allow a numeric value to be set to zero or a character field to be cleared, in which case we mark the field as not required. The records used for all Oracle delivered templates are TL_TMPLT_RULE (the actual table on the header page) and DERIVED_TL_TMPL (the work record on the detail page).


15

Field Format: This is taken from the definition of the field you select, except for the Character Without Quotes selection. This deals with the formatting of the parameter into the SQL statement. A character value typically has quote wrappers (…AND TRC = ‘KUREG’…), but there are special cases when quote wrappers are not desired, and that is when we deal with logical or mathematical operators. To prevent the character > to be formatted as AND TL_QUANTITY “>” 40, select Character Without Quotes for this character parameter. Time Selection: There is a recurring construct that does not use field or list, but indicates the time entries to include using the collection of checkboxes on the header page:

Snapshot from Template-Based Rule Header Page

To transform that into the correct syntax for the SQL, indicate the parameter as follows: Record is TL_TMPLT_RULE, no field, List Type is Punch Type.


16

Template Step Parameters page with generic rule expression

Based on the example above, this is then converted to:

Run-Time executable - Sample

Identify and Develop App Class Logic - “Optional”

This step is optional because in the latest version of the Rule Template feature you are now likely done.

Template Controlling Code parameters – Optional and mostly not needed

In the prior version every template required the development of a dedicated app class to support building rules for that particular template. There were also other PeopleCode events that used the template ID to determine the behavior and the logic to execute. This made it impossible to create new templates without customizing the system by modifying Oracle-delivered code. Particular requirements may still demand such logic, but it is the exception. Among the 50+ templates currently available, only 12 did not fit the generic mold. More importantly, the new model enables you to place this code in your choice of locations so that it is not affected by updates to code delivered by Oracle. If the template is a “vanilla” template, deselect the “Use Dedicated App Class” check box and you are done. If you are developing an Oracle-delivered template and need specific logic, then select the field and specify TL_RULETEMPLATES as the Root Package ID. For such a template you need to create an app class. There are 3 requirements for this app class.


17

• The App Class name, not the package, must be identical to the template ID. (For TEMPLATE060 we have the app class TEMPLATE060.)

• Oracle-delivered templates must be placed in the TL_RULETEMPLATES:PSFT package. Others can go anywhere; a key feature of the new design.

• Your app class must extend the Oracle-delivered TemplateMaster class. TEMPLATE000Explained offers more information about how you code your app class. Its location is identified in the picture below:

Oracle-delivered Application Class for additional template controlling code – Snapshot from PSIDE

As mentioned earlier there are four areas, or methods involved:

• Building the rule. • Loading and presentation of the template rule on the UI. • Formatting the rule explanation text. • Validating the data entered to create the rule.


18

Methods available in the template-controlling code master

The generic template model may not meet the needs of your template in one or more of these areas. So you must override parts or all of the logic found in the super class TemplateMaster() as required for your purpose. Chapter 4 offers some examples regarding why and how to override the standard logic.

Packaging

Beyond the standard PeopleTools objects and the message catalog entry, a template typically consists of data in four, and sometimes five, different tables that need to be packaged and delivered as SYSTEM data. Presently there is no vehicle, such as export / import rules, to support the transfer of templates from one environment to another. This may change once a demand is established.

TABLE Description

TL_TMPLT_DEFN Rule Template Definition The main definition.

TL_TMPLT_PARMS Rule Template Parameters The parameters tied to the steps.

TL_TMPLT_PARMT Rule Template Text Parameters The parameters linked to the rule explanation.

TL_TMPLT_STEPS Rule Template Steps


19

TL_TMPLT_CONDS TL Template Conditions Tied to Action objects. Only found under TEMPLATE130.

When Do I Need Template Controlling Code

That is not easily answered since it is hard to be specific about possible – and perhaps unforeseen – exceptions that do not fit the mold. However, here are some examples:

Rule Text [TEMPLATE060]

This template appends a different sentence to the rule description based on the “when to create” option. This is a one-off situation that is hard to identify in ways other than to say “if the template is TEMPLATE060, then do this…” and that should be avoided in the vanilla solution.

Rule Detail Page for Template060-based rules

Coding the dedicated app class / method override however, is simple:


20

Template-Controlling code for Template060

Presentation [TEMPLATE160]

In the presentation area this is either about very specific data conversion from stored format to displayed format, or it is about the time selection (also known as punch types – although elapsed time is not a type of punch, is it?).

Header page snapshot

For exotic variations in this area you may need to create the app class and use code like the following:


21


Validation [TEMPLATE300]

Rules from this template require a certain relationship between the calendar, or Period, on the header page and the one selected on the rule detail page:

Rule Detail page for Template300

There is special validation involved to ensure that one fits with the other. This is another example of a requirement that is hard to fit into a generalized mold:


22


Building Rule [TEMPLATE090]

Template Rule building has two outputs:

• The physical rule definition stored in TL_RULE_DEFN, TL_RULE_STEPS (and TL_RULE_CONDS) table. This version of the rule also enables a rule developer to create a different rule using a template as a base.

• The AE program section with the expanded executable SQL statements. Time variables in SQL are converted and stored as numbers, represented as time in minutes where midnight is 0, 1 AM is 60, and so on through 1440.


23

Rule Detail page for Template090

To deal with this conversion, we need more logic that is hard to can for generic purposes. Time may not always need to be converted and there may not always be a start and stop relationship to worry about. In this case we re-format the data in TL_TMPLT_RULEP before storing and compiling the rule.



24

Create Templates Using the new Generic Entry Pages

This chapter illustrates the exercise of creating a new template and using the new generic entry pages for rule creation. Note: The SQL object selected for this exercise is not compatible with the rule input and would not create a functioning rule, but it enables the illustration of as many of the aspects of the generic page interface as possible.

Set Up the Pre-Requisites

Pre-Requisite One: Create or Select Rule Objects

For the sake of illustration, SQL Object TMPL050_S010 was chosen because it requires four parameters, which is a good number to play with a variety of parameters of different formats. Creating the SQL objects is otherwise the central and most difficult task of setting up a template or a rule. Course material on Building Time and Labor rules covers this skill in depth.

Pre-Requisite Two: Create or Select a Page

Assuming I am reluctant to add my own pages to the component that is delivered and maintained by Oracle, I may opt to settle for one of the generic UI’s. That means there is no page for me to create. These pages were intended for custom template building by customers and should not be used for templates that are delivered as part of the product – whether they originate within the development organization or one of the consulting branches such as GSC or CoE.

Pre-Requisite Three: Create or Select a Rule Explanation Message

This is the text that is displayed as the explanation for the rule, and is updated and stored along with each rule created based on this template.


25

Expanded Explanation text for Template010 rule KAOVT1.5

For this illustration I create a simple, generic message to verify the transformation as well as some field formatting.

Message Catalog Page

Normally, to avoid using Oracle delivered objects I would not have picked message set 13507 because this is a set maintained by product development, but bear with me on this exception.

Pre-requisite Four: Create or Select Parameter Record

Continuing to work under the restriction that I do not want to modify delivered objects I create a new record called DERIVED_CUST. As the name suggests, the record type is Derived/Work.


26

Snapshot of DERIVED_CUST Record Object Definition from PSIDE

Create the Template

The first custom template is called CUSTOM01. The important pieces here are the Detail Page selection and the Message Set / Number selection.

The Main Template Definition

Text Parameters

I select all of the parameters from the record that I dedicated for this template, matching them with the placeholders created in the message text:


27

Matching parameters to the Explanation Text

Template Steps

For the sake of illustration, I include steps that clean up and then update statistics on my chosen work table. The selected SQL object does not operate on this particular table, but if Step 20 was defined with a statement that copied a set of rows from the main TL_IPT1 repository into the TL_IPT2 table for further manipulation the graphic below illustrates the typical sequence of events.

Defining the Template Rule Steps

Template Parameters

I enter my parameters, matching them with the appropriate position in the SQL statement provided in the step. I indicate that TL_QUANTITY is not a required parameter, which means that rule-creators can use the value 0.


28

Matching display fields to the step parameters

NOTE: If you forget to specify the parameters or specify too few or too many, the system generates a message to notify you.

Sample Error message

Test-drive the Template

I add my first rule under the new template, verifying in the process that it is using the page I selected.


29

Scroll-based Generic Rule Detail page assigned to the CUSTOM01 template

To verify more of the built-in features, I enter test data, first to verify that the explanation field is satisfactorily filled in.

Explanation Updated from Parameter Values entered


30

Built-In Data Validation

Attempts to enter data in the wrong format are indicated using the methods made available by PeopleTools:

Data Validation Example


31

More Data Validation Examples

After correcting the mistakes and correctly formatting the parameters, I modify the template switching interface pages from TL_TEMPLATE_GEN to TL_TEMPLATE_GRID.

Switching to the other generic Rule Detail page

When I return to the Template-Built Rules component and re-open my newly created rule I can verify that the display page has changed.

Grid-based Generic Rule Detail page

Since it is difficult to accommodate all uses with a single field, which may use different formats, some with prompting, some without, we must use different fields to support the entry of fields of a different nature. Some users prefer the grid display over the scroll approach, but it may be better


32

suited when the types of parameters involved is more homogenous, for example: all characters or all numeric.

Things We Worry About

Performance, Performance, Performance

The effort to deliver the new interface for template maintenance was born from the need to upgrade delivered templates, and performance tuning was a big part of that. A template rule does not really introduce anything not already enabled by the basic rule building toolset, except that it should enable those involved to create more rules faster. Beyond the basic understanding that SQL statements must be built with efficiency in mind, there is also the use of Truncate and Update Statistics that may work well for bigger batch jobs, but are less optimal for jobs with lower data volumes. This may be the case for the expanded “Apply Rules” capability being rolled out in release 9.2 and require rules and template creators to monitor their creation for performance and efficiency.

Conclusion

Templates Made Available offers a PeopleSoft Internet Architecture (PIA) interface to maintain rule template definitions that can greatly improve the ability to configure and maintain a much wider and flexible set of rules catering to customer needs. Through increased configurability, it allows the creation and maintenance of new templates in isolation from Oracle delivered objects, thus eliminating many concerns linked to future product upgrades.

Templates Made Available – Creating Rule

Templates

May 2011

Author: Gunnar Roy Hansen

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 © 2011, Oracle and/or its affiliates. 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 and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license

and are trademarks or registered trademarks of SPARC International, Inc. UNIX is a registered trademark licensed through X/Open

Company, Ltd. 1010

Documents

HCM 9x TL Templates Made Available White Paper Final