Sie sind auf Seite 1von 36

Templates Made Available Creating Rule Templates

An Oracle White Paper May 2011

Templates Made Available Creating Rule Templates

Templates Made Available Creating Rule Templates

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 Oracles products remains at the sole discretion of Oracle.

Templates Made Available Creating Rule Templates

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

Templates Made Available Creating Rule Templates

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 workers 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.

Templates Made Available Creating Rule Templates

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 templates explanation and the templates executable steps, or SQL objects.

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

Templates Made Available Creating Rule Templates

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.

Templates Made Available Creating Rule Templates

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.

Templates Made Available Creating Rule Templates

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.

Templates Made Available Creating Rule Templates

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.

Templates Made Available Creating Rule Templates

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

Templates Made Available Creating Rule Templates

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.

Templates Made Available Creating Rule Templates

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

Templates Made Available Creating Rule Templates

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.

10

Templates Made Available Creating Rule Templates

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.

11

Templates Made Available Creating Rule Templates

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

12

Templates Made Available Creating Rule Templates

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:

13

Templates Made Available Creating Rule Templates

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).

14

Templates Made Available Creating Rule Templates

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.

15

Templates Made Available Creating Rule Templates

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.

16

Templates Made Available Creating Rule Templates

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.

17

Templates Made Available Creating Rule Templates

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 TL_TMPLT_DEFN TL_TMPLT_PARMS TL_TMPLT_PARMT TL_TMPLT_STEPS

Description Rule Template Definition The main definition. Rule Template Parameters The parameters tied to the steps. Rule Template Text Parameters The parameters linked to the rule explanation. Rule Template Steps

18

Templates Made Available Creating Rule Templates

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:

19

Templates Made Available Creating Rule Templates

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:

20

Templates Made Available Creating Rule Templates

Template-Controlling code for Template160

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:

21

Templates Made Available Creating Rule Templates

Template-Controlling code for Template300

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.

22

Templates Made Available Creating Rule Templates

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.

Template-Controlling code for Template090

23

Templates Made Available Creating Rule Templates

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 UIs. 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.

24

Templates Made Available Creating Rule Templates

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.

25

Templates Made Available Creating Rule Templates

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:

26

Templates Made Available Creating Rule Templates

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.

27

Templates Made Available Creating Rule Templates

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.

28

Templates Made Available Creating Rule Templates

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

29

Templates Made Available Creating Rule Templates

Built-In Data Validation

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

Data Validation Example

30

Templates Made Available Creating Rule Templates

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

31

Templates Made Available Creating Rule Templates

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.

32

Templates Made Available Creating Rule Templates May 2011 Author: Gunnar Roy Hansen

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 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 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