Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
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.
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
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.
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.
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:
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.
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.
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.
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.
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.
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
The header page region controls three fields or areas on the Template Header page.1
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.
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.
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.
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.
When you specify a Rule Explanation message, you need to point to the right parameter for each placeholder in the template message.
10
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
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
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:
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.
This portion of the template is taken from the original design. The template steps define the rule logic.
12
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.
The interface behind the parameters link enables the parameter mapping while displaying the template SQL for guidance:
13
There are additional items that were not an issue on the rule text parameter 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
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:
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
This step is optional because in the latest version of the Rule Template feature you are now likely done.
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
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
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
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.
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
TL_TMPLT_CONDS
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.
19
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?).
For exotic variations in this area you may need to create the app class and use code like the following:
20
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:
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
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
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.
23
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.
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
For this illustration I create a simple, generic message to verify the transformation as well as some field formatting.
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
The first custom template is called CUSTOM01. The important pieces here are the Detail Page selection and the Message Set / Number selection.
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
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.
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
NOTE: If you forget to specify the parameters or specify too few or too many, the system generates a message to notify you.
I add my first rule under the new template, verifying in the process that it is using the page I selected.
28
To verify more of the built-in features, I enter test data, first to verify that the explanation field is satisfactorily filled in.
29
Attempts to enter data in the wrong format are indicated using the methods made available by PeopleTools:
30
After correcting the mistakes and correctly formatting the parameters, I modify the template switching interface pages from TL_TEMPLATE_GEN to TL_TEMPLATE_GRID.
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.
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
suited when the types of parameters involved is more homogenous, for example: all characters or all numeric.
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