Oracle Applications
Oracle Time and Labor
Configuring The Oracle Time and Labor Timecard User Interface
White Paper
∗
Author(s): Oracle Time and Labor Development
Generation Date: June 7, 2012
Abstract
This document details the configuration options a timecard layout designer has when constructing a custom layout. OTL currently allows customization of timecard layouts via modification of AOL loader files which are then loaded into the database.
c
2012 Oracle Corporation. All rights reserved.
Contributors
Name Position
Mark Stewart Applications Developer
Andrew Rundell Development Manager
Joel Dupont Applications Developer
John Finnegan Principle Functional Analyst
Kris Van Der Pleog Functional Analyst
Anima Prasad Group Manager
Balakrishna Bayragi Senior Applications Engineer Amarnath Krishnamoorthy Senior Applications Engineer
Change Record
Date Author Version Change Reference
February 1st, 2005 Andrew Rundell 115.0 Converted to PDF, WIKI, LaTeX
August 6th, 2007 Amritha Nuthi 115.1 Modified to indicate correct functionality for
package choice list
March 25th, 2008 Amritha Nuthi 115.2 Modified to show only the delivered seeded layouts and
to complete the missing lines in some examples
February 09th, 2010 Amarnath Krishnamoorthy 115.3 Reviewed the document and added few examples which describes how to create custom choice list, LOV, prompts and text field June 07th, 2012 Balakrishna Bayragi 115.4 Added section 3.18
Reference Documents
Name Description
Release 11i Documentation Oracle Applications Documentation - information on FNDLOAD and Flexfields
ADF Applications Development Framework - information on java
Contents
1 Introduction 8
1.1 Executive Overview . . . 8
1.2 Structure of a Timecard Page . . . 9
1.2.1 Time Building Blocks . . . 9
1.2.2 User Interface Component Hierarchy . . . 9
1.3 Layout Types . . . 10
1.4 Delivered Layouts . . . 11
1.4.1 Payroll . . . 13
1.4.2 Projects . . . 13
1.4.3 Projects and Payroll . . . 14
1.4.4 Exception . . . 15
1.4.5 Enterprise Asset Management . . . 15
1.4.6 Purchasing . . . 15
1.4.7 Projects-Purchasing . . . 16
1.4.8 Payroll Layout delivered in Release 12.1 . . . 16
1.4.9 Project Layouts delivered in Release 12.1 . . . 17
1.4.10 Project and Payroll Layouts delivered in Release 12.1 . . . 17
1.5 Using the OAF Personalization Functionality With Timecard Configuration . . . 19
2 Timecard Configuration Basics 20 2.1 What can be configured on a Timecard . . . 20
2.2 The Layout File . . . 21
2.3 Using an Existing Layout as a Basis for Customization . . . 21
2.4 Uploading Timecard Layouts . . . 21
2.5 Labels and Messages . . . 22
2.5.1 Labels . . . 22
2.5.2 Messages . . . 22
2.6 Further Configuration Concepts . . . 22
2.6.1 View Objects . . . 22
2.6.2 Application Modules . . . 23
2.6.3 Apache/JServ server . . . 23
2.7 Delivered Configurable BC4J Objects . . . 23
2.7.1 Configurable Choice List Components . . . 23
2.7.2 Package Choice List . . . 24
2.7.3 Custom Alternate Name components . . . 26
2.8 LOVs and JRAD/MDS . . . 28
2.8.1 LOV Custom Objects . . . 28
3 Examples of Common Customizations 29 3.1 Adding a Comment Field to the Timecard Line . . . 29
3.2 Adding a Custom Choice List to the Timecard . . . 30
3.3 Adding a Custom LOV to the Timecard using the Custom LOV Objects . . . 31
3.3.1 Create the supporting database view . . . 32
3.3.2 Add the LOV component to the timecard . . . 34
3.3.3 Personalize the LOV region . . . 36
3.4 Adding a Custom LOV to the Timecard without using the Custom LOV Objects . . . 37
3.4.1 Create the View Object for the LOV . . . 37
3.4.2 Create AK attributes used for the LOV screen . . . 38
3.4.3 Create an AK region for rendering the LOV screen . . . 40
3.4.5 Run the migration script to copy the LOV definition from AK to the MDS repository . . . 42
3.4.6 Modify a layout to include the LOV component . . . 42
3.4.7 Include the new LOV View Object into your Apache/Jserv environment . . . 43
3.5 Changing the title of the timecard page . . . 43
3.6 Changing the label for a column in the Timecard . . . 43
3.7 Adding a Component to the Timecard Header . . . 45
3.7.1 Create AK data for the component prompt . . . 51
3.7.2 Create wrapper PL/SQL function to call the payroll code function and return it in the format needed for the package choice list . . . 51
3.7.3 Create the component to show the label for our custom field and add it to the layout . . . 52
3.7.4 Create the component to show the read-only function result and add it to the layout . . . 52
3.8 Adding a Component to the Timecard Matrix . . . 53
3.9 Adding an OTL Information Type to the Timecard . . . 62
3.10 Adding additional element input values . . . 63
3.11 Configuring the Cost Center component . . . 64
3.12 Adding OTLR Detail to the Review and Confirmation Pages . . . 67
3.12.1 Creating the Detail Time Building Blocks in the Layout . . . 68
3.13 Adding the Details Page DFF Segments to the Timecard matrix . . . 68
3.13.1 Setting the Attribute Category . . . 68
3.13.2 Aliasing A Segment Value To Set The Attribute Category . . . 69
3.13.3 The Simple Approach: An Always-execute choice list . . . 72
3.13.4 Other Segment Values . . . 73
3.14 Configure Expenditure Type As Choice List Using Alternate Names in Projects Payroll Layout . . . 74
3.14.1 Define a New OTL Alternate Names Type Descriptive Flexfield Context / Segment: . . . 74
3.14.2 Mapping the Segments/Attributes to respective components: . . . 75
3.14.3 Creating Alternate Name for the Alternate Name Type ET EXPENDITURE TYPES: . . . 75
3.14.4 Create A Custom View and Define Layouts: . . . 76
3.15 Configuring Cost Center as a LOV in Payroll Layout . . . 78
3.15.1 Create AK attributes used for the LOV screen : . . . 79
3.15.2 Create an AK region for rendering the LOV screen: . . . 79
3.15.3 Create AK region items inside the AK region for the LOV page: . . . 79
3.15.4 Migration of Ak Region to MDS Repository,Creation of Custom View and Define Layouts: . . . 80
3.16 Adding Custom LOVs, Custom Choice List and Text Field to a Payroll Layout . . . 83
3.16.1 Create AK attributes: . . . 85
3.16.2 Add Attributes to AK Region: . . . 87
3.16.3 Create database views: . . . 87
3.16.4 Create AK regions for rendering the LOVs: . . . 88
3.16.5 Create AK region items inside the AK region for the LOV page: . . . 90
3.16.6 Setting up the Custom LOV xml and java files: . . . 92
3.16.7 Migration of Ak Region to MDS Repository: . . . 93
3.16.8 LDT file customization to change prompt from Hours Type to Job Type: . . . 95
3.16.9 LDT file customization to include choice list: . . . 95
3.16.10 LDT file customization to include source and destination LOVs: . . . 97
3.16.11 LDT file customization to include text field: . . . 99
3.17 Configure an Entry Level Processing Timecard Layout to capture Project, Task and Expenditure Type Information in Cost Allocation Key Flexfield segments . . . 100
3.17.1 Create AK attributes: . . . 102
3.17.2 Add Attributes to AK Region: . . . 103
3.17.3 Create database views: . . . 104
3.17.4 Add Project Id, Task Id and Expenditure Type segments to Cost Allocation KFF: . . . 104
3.17.6 LDT file hxczzhxclayt0025.ldt customization to add Cost Center field: . . . 106
3.17.7 LDT file hxczzhxclayt0025.ldt customization to map Project Information to Cost Allocation KFF: . . . 107
3.17.8 Attributes data stored in database: . . . 112
3.17.9 Batch Element Entry form showing the additional segments in Cost Allocation KFF: . . . 113
3.18 Confirmation Check box on Timecard review page for Time Accuracy . . . 114
4 Technical Reference Guide 116 4.1 Components . . . 116
4.1.1 Global attributes . . . 116
4.1.2 Accrual Balance Component . . . 118
4.1.3 Choice List . . . 118 4.1.4 Descriptive FlexField . . . 120 4.1.5 Display Header . . . 121 4.1.6 Display Label . . . 121 4.1.7 Display Text . . . 121 4.1.8 Hidden Field . . . 121
4.1.9 Hours Type Table . . . 121
4.1.10 Inter-Period Navigation Control . . . 121
4.1.11 Key Notation . . . 122
4.1.12 List Of Values . . . 122
4.1.13 Message Box . . . 125
4.1.14 Notification Day Detail . . . 125
4.1.15 Package Choice List . . . 125
4.1.16 Page Status . . . 125 4.1.17 Spacer . . . 126 4.1.18 Submit Button . . . 126 4.1.19 Submit Icon . . . 126 4.1.20 Summary Table . . . 127 4.1.21 Table Layout . . . 127 4.1.22 Template Control . . . 128 4.1.23 Text Field . . . 128
4.1.24 Timecard Fragmentation Cluster . . . 128
4.1.25 Time Building Block . . . 128
4.2 Tokens . . . 128
4.3 Seeded Prompts . . . 129
4.3.1 HXC CUI TIMECARD Region . . . 129
4.3.2 HXC CUI TIMECARD REVIEW Region . . . 129
4.3.3 HXC CUI TIMECARD CONFIRMATION Region . . . 129
4.4 Seeded Messages . . . 129
4.5 CUI Error Codes . . . 129
5 Troubleshooting and Frequently Asked Questions 138 5.1 FAQ . . . 138
List of Tables
1 Payroll Layouts . . . 13
2 Projects Layouts . . . 13
3 Projects and Payroll Layouts . . . 14
4 Exception Layouts . . . 15
5 Enterprise Asset Management Layouts . . . 15
6 Purchasing Layouts . . . 15
7 Projects-Purchasing Layouts . . . 16
8 R12.1 Payroll Layouts . . . 16
9 Projects Layouts - With Project & Task details concatenated . . . 17
10 Projects and Payroll Layouts - With Project & Task details concatenated . . . 18
11 Delivered Custom Choice List View Objects . . . 24
12 Component Tables Key . . . 116
13 Global Attributes, applicable to every component. Required attribute(s) in bold. . . 117
14 Choice List Components. Required Attribute(s) are displayed in bold. . . 119
15 Descriptive flexfield component qualifing attributes. Required attribute(s) are displayed in bold. . . 120
16 Display text component qualifing attributes. Required attribute(s) are displayed in bold. . . 121
17 Inter Period Navigational Control component qualifing attributes. Required attribute(s) are displayed in bold. . . 121
18 Key notation component qualifing attributes. Required attribute(s) are displayed in bold. . . 122
19 List of Values component qualifing attributes. Required attribute(s) are displayed in bold. . . 124
20 Message Box component qualifing attributes. Required attribute(s) are displayed in bold. . . 125
21 Package Choice List component qualifing attributes. Required attribute(s) are displayed in bold. . . 126
22 Page Status component qualifing attributes. Required attribute(s) are displayed in bold. . . 126
23 Spacer component qualifing attributes. Required attribute(s) are displayed in bold. . . 126
24 Submit Button component qualifing attributes. Required attribute(s) are displayed in bold. . . 127
25 Submit Icon component qualifing attributes. Required attribute(s) are displayed in bold. . . 127
26 Summary Table component qualifing attributes. Required attribute(s) are displayed in bold. . . 127
27 Table Layout component qualifing attributes. Required attribute(s) are displayed in bold. . . 128
28 Template Control component qualifing attributes. Required attribute(s) are displayed in bold. . . 128
29 Text Field component qualifing attributes. Required attribute(s) are displayed in bold. . . 129
30 Time Building Block component qualifing attributes. Required attribute(s) are displayed in bold. . . 130
31 Currently recognized tokens . . . 131
32 Timecard region seeded prompts (Part 1.) . . . 132
33 Timecard region seeded prompts (Part 2.) . . . 133
34 Timecard Review region seeded prompts . . . 134
35 Timecard Confirmation region seeded prompts . . . 134
36 Seeded Timecard Messages . . . 135
37 Configurable User Interface Error Codes . . . 136
List of Figures
1 Time Building Blocks . . . 12
2 What can be Configured . . . 20
3 Timecard Matrix Line Comment Field . . . 30
4 Alternate Name Definition . . . 32
5 Custom LOV Showing Locations . . . 37
6 Custom LOV Showing Locations after personalization . . . 38
7 Defining New OTL Alternate Name . . . 74
8 Mapping Segements/Attributes to respective components . . . 75
9 Preference Page . . . 76
10 Time Entry Page . . . 78
11 AK Region . . . 79
12 AK Region items . . . 80
13 Preference page . . . 82
14 Time Entry Page . . . 82
15 Configured Airlines Timecard . . . 83
16 Additional Element Input Values . . . 84
17 AK Attributes . . . 85
18 Add Attributes . . . 87
19 LOV AK Region . . . 89
20 LOV AK Region items . . . 91
21 Flight Source and Destination LOVs . . . 94
22 Configured ELP Timecard . . . 100
23 Additional Element Input Values . . . 101
24 AK Attributes . . . 102
25 Add Attributes . . . 103
26 Cost Allocation KFF Segments . . . 104
27 HXC TIME ATTRIBUTES table data . . . 112
28 Cost Allocation KFF Segments in BEE . . . 113
Preface
Audience
This document describes the Oracle Time and Labor configurable timecard interface. It is a How-To guide as well as technical reference document. In order to configure an Oracle Time and Labor timecard user interface working knowledge of the Oracle Applications generic loader, FNDLOAD, plus its associated pre-requisite knowledge, as well as a basic understanding of a web page and Oracle Flexfields is required. For more complex configurations, such as custom list of values, some familiarity with the Oracle Applications Development Framework (ADF) is required. For example, additional list of values may require new ADF components such as View Objects. Consult the appropriate reference documents for more detailed information on these Oracle Application specific features.
Document Structure
There are five sections to this document:
• Section 1 provides introductory material, including and executive overview, which is appropriate background reading for people wishing to understand, but not implement a configurable user interface.
• Section 2 describes the basics of timecard configuration, and at high level discusses the various objects and techniques employed when modifying the interface.
• Section 3 builds on the previous section to provide explicit examples of typical configurations, e.g. changing the window title, adding a choice list and a list of values.
• Section 4 supplies a full technical reference guide for all configurable components and objects associated with the configurable user interface.
• Finally, section 5 describes what to do in the case of an unexplained configuration error, and contains a list of frequently asked questions.
For very simple timecard configurations, e.g. just changing a prompt or moving a field from one place to another, only the first three sections are required reading. For more complex configurations, e.g. adding a dependent list of values, the technical reference section is invaluable.
This version of the document applies to HXT.H onwards, Oracle Applications Release 11i.10, Release 12.0 and Release 12.1
1
Introduction
1.1
Executive Overview
Oracle Time & Labor (OTL) permits configuration of the timecard interface. Inclusion or exclusion of UI features, e.g. labels and buttons, as well as choosing the fields shown on the timecard lie within the configuration module. These fields can be the delivered set, or custom fields, tailored to a particular business.
The timecard interface is a hierachical structure of user interface components, a full set of which describes the interface, and is known as a layout. Currently, a layout describes the user interface for one page, and thus there are OTL layouts for the timecard entry, review, confirmation, notification, approval, audit and details pages, as well as a layout that describes what information is available for offline time entry — the export layout. This enables the maximum level of configuration. Layouts are held in normal text files; these are loaded into the database using the standard applications loader utility (FNDLOAD), and configuration file supplied by OTL. There are many delivered layouts that provide a timecard user interface configured for various applications, or combinations of applications and these are pre-loaded for immediate use.
The appearence of the user interface components contained in a layout are controlled via varying sets of information, such as height, color, size, direction, data source and so on. This extra information is held in a standard Oracle Applications Flexfield, called Self Service Configurable UI Flexfield. Each of the user interface components has a context within this flexfield, the segments
of which are known as component qualifiers, or just qualifiers. The column names in the OTL database for these qualifiers are QUALIFIER ATTRIBUTE1 through QUALIFIER ATTIRBUTE30. Use of a flexfield to store this extra information ensures a consistent approach to user interface components within the configurable user interface module, and makes it easier to add support for additional components in the future.
In conjuction with the standard Oracle Applications Development Framework (ADF) personalization feature, the OTL timecard configurable user interface module permits every aspect of the timecard page to be changed, within the normal limits of HTML.
When configuring a timecard page, it is important to understand how the user interface components relate to the data generated in the OTL time store. In this way, the most appropriate configuration is efficiently and accurately created. This document uses many OTL concepts to streamline the configuration for the application, and thus the relationship between the data and the user interface components on the page is now described.
1.2
Structure of a Timecard Page
1.2.1 Time Building Blocks
When entering time, you actually create objects (database records) called time building blocks. Time entry for a particular day creates a new time building block, each entry being a separate block. Each time building block may store information about what that time represents; these are time building block attributes.
There are two types of time building blocks:
• A range time building block is an entry of time that exists for a given range of time, for instance, today from 9:00 AM until 5:00 PM, or from August 20th to August 26th.
• A measure time building block is an entry of time that is a specific amount of time. For this type of time building block there is no information within the block itself about when this time occurred.
The OTL timecard data-structure is a hierarchical collection of time building blocks. The top time building block (the one without a parent) is the TIMECARD time building block, and represents the range of time for which this timecard exists, such as a week or a month.
Time building blocks have one or more child blocks and one parent block. You can attach blocks to other blocks, and build the complete timecard for a period of time. Each day associated with this timecard is a child time building block of that TIMECARD time building block. Day building blocks are range building blocks, and represent the amount of time within that day (they start at midnight on that particular day, and end at one second before midnight on the same day). Each day may have one or more time building blocks associated with it, and these are the time entries associated with the timecard.
The data model reflects the user interface of the timecard page. Consider a square split in half. This square represents the screen, and in one half, we render the attributes associated with the TIMECARD time building block, such as the comment text field, in the other half, we render all the child building blocks of this block, the days and entries. Next, the process occurs for these child blocks, namely a square split in half, in one half we render the attributes the other we render the child building blocks of this block, and so on. This is shown in Figure 1 below:
In this way, we can easily represent the hierarchical structure of the set of blocks that make up the timecard on the screen. However, simply doing that can lead to a confusing and repetitive user interface. To avoid this, the user interface component qualifiers are used to ensure that the timecard user interface makes sense. However, in principle, it is clear that there is a correspondance between the hierarchical nature of the user interface components, and the hierarchical nature of the time store building block data structure. 1.2.2 User Interface Component Hierarchy
As previously mentioned, user interface components — hereafter known simply as components — are the objects belonging to a timecard layout to make up the page.
Although the components on each layout can be very different they all follow a similar hierarchy - an example of this hierarchy can be seen below:
• message box components to be show for errors/warnings/confirmations • page status
• top level building block – header table layout
∗ header field table layout
· inter-period navigation control label · inter-period navigation control component · override approver label
· override approver component · template control label · template control component ∗ comments component
– timecard matrix building block ∗ measure field
∗ project LOV ∗ task LOV
∗ expenditure type LOV ∗ delete control
∗ details control
– template save table layout ∗ save template name field ∗ save template submit control
You will note the use of tables within this hierarchy - this is the primary way of formatting or aligning fields in HTML. So for example, in the header table the outer table definition allows us to show the navigation/override/template fields on one side of the page and the comments field on the other side. The nested table allows us to make sure that the field labels and components are aligned with each other to improve the visual appearance of the page. Note: For readers experienced with the ADF, it is clear that each of these OTL configurable user interface components maps to a OAF web bean, and that the hierarchy described here is added in its entirity to the web bean hierarchy used by OAF to render self service pages.
1.3
Layout Types
Each layout contains the component hierarchy definition for one page. Thus, it is beneficial to describe a layout by functional type of page defined by that layout. Thus, we consider the following layout types:
• timecard (time entry page) • review (timecard review page)
• confirmation (timecard confirmation page) • details (timecard details page where applicable)
• export (template used for the timecard export functionality)
• notification (timecard review page as seen by the timecard approver)
• fragment (timecard review page as seen by an approver, but containing only those time entries for which the approver can approve time, e.g. all the projects entries, all the payroll entries — this layout type is used in conjunction with the Entry Level Approval functionality of OTL
• audit (the page on which audit entries, also known as reasons, are made)
A group of layouts comprising one layout from each type with common application fields, e.g. Payroll Timecard Layout, Payroll Review Layout, Payroll Confirmation Layout, Payroll Notification Layout etc., is sometimes referred to as a layout set.
1.4
Delivered Layouts
In order to facilitate rapid implementation, a number of common timecard layout sets are delivered with OTL. These meet many requirements for capturing time, or can be used as the basis for customization.
Find these layout files in $APPL TOP/hxc/11.5/patch/115/import/US/, where $APPL TOP is the mount and directory where Oracle Applications is installed. These layout sets are named after the application-specific data entry fields defined within them, e.g. the Projects layout set contains components for a Project entry field, a Task entry field, an expenditure type field and so on. There are four application-specific layout sets delivered with the OTL product: Payroll, Projects, Projects and Payroll — these are layouts with both the projects application and payroll application fields defined, and an Exception-based time reporting layout.
1.4.1 Payroll
The payroll layouts delivered with the product are listed in table 1.
Layout Name Layout Code Layout Type Filename
Payroll Timecard Layout PAYROLL-TIMECARD TIMECARD hxczzhxclayt0000.ldt
Payroll Review Layout PAYROLL-REVIEW REVIEW hxczzhxclayt0005.ldt
Payroll Confirmation Layout PAYROLL-CONFIRMATION CONFIRMATION hxczzhxclayt0001.ldt
Payroll Export Timecard Layout PAYROLL-EXPORT-LAYOUT EXPORT hxczzhxclayt0002.ldt
Payroll Fragmented Timecard View PAYROLL-FRAGMENT FRAGMENT hxczzhxclayt0003.ldt
Payroll Notification Layout PAYROLL-NOTIFICATION NOTIFICATION hxczzhxclayt0051.ldt
Payroll OTLR Details Review Layout PAYROLL-HE-REVIEW REVIEW hxczzhxclayt0004.ldt
Payroll OTLR Details Notification Layout PAYROLL-HE-NOTIFICATION NOTIFICATION hxczzhxclayt0047.ldt
Table 1: Payroll Layouts
1.4.2 Projects
The projects layouts delivered with the product are listed in table 2.
Layout Name Layout Code Layout Type Filename
Projects Timecard Layout PROJECTS-TIMECARD TIMECARD hxczzhxclayt0019.ldt
Projects Review Layout PROJECTS-REVIEW REVIEW hxczzhxclayt0020.ldt
Projects Confirmation Layout PROJECTS-CONFIRMATION CONFIRMATION hxczzhxclayt0017.ldt
Projects Details Layout PROJECTS-DETAIL DETAIL hxczzhxclayt0065.ldt
Projects Export Timecard Layout PROJECTS-EXPORT-TIMECARD EXPORT hxczzhxclayt0018.ldt
Projects Notification Layout PROJECTS-NOTIFICATION NOTIFICATION hxczzhxclayt0052.ldt
Projects Fragmented Timecard View PROJECTS-FRAGMENT FRAGMENT hxczzhxclayt0058.ldt
Projects Change and Late Audit En-try Layout
PROJECTS-AUDIT-LAYOUT AUDIT hxczzhxclayt0014.ldt
Projects Change and Late Review Layout
PROJECTS-AUDIT-REVIEW REVIEW hxczzhxclayt0016.ldt
Projects Change and Late Confirma-tion Layout
PROJECTS-AUDIT-CONFIRMATION CONFIRMATION hxczzhxclayt0013.ldt
Projects Change and Late Audit No-tification Layout
PROJECTS-AUDIT-NOTIFICATION NOTIFICATION hxczzhxclayt0048.ldt
1.4.3 Projects and Payroll
The projects-payroll layouts delivered with the product are listed in table 3.
Layout Name Layout Code Layout Type Filename
Projects and Payroll Timecard Layout PROJECTS-ALTERNATE-TIMECARD TIMECARD hxczzhxclayt0015.ldt
Projects and Payroll Review Layout PROJECTS-ALTERNATE-REVIEW REVIEW hxczzhxclayt0010.ldt
Projects and Payroll Confirmation Lay-out
PROJECTS-AL-CONFIRMATION CONFIRMATION hxczzhxclayt0007.ldt
Projects and Payroll Details Layout PROJECTS-ALTERNATE-DETAIL DETAIL hxczzhxclayt0012.ldt
Projects and Payroll Export Layout PROJPAYROLL-EXPORT-LAYOUT EXPORT hxczzhxclayt0021.ldt
Projects and Payroll Notification Layout PROJECTS-ALTERNATE-NOTIF NOTIFICATION hxczzhxclayt0053.ldt
Projects and Payroll Fragmented Time-card View
PROJECTS-ALTERNATE-FRAGMENT FRAGMENT hxczzhxclayt0009.ldt
Projects and Payroll Change and Late Audit Entry Layout
PROJECTS-ALT-AUDIT-LAYOUT AUDIT hxczzhxclayt0034.ldt
Projects and Payroll Change and Late Review Layout
PROJECTS-ALTERNATE-CLA-REVIEW REVIEW hxczzhxclayt0033.ldt
Projects and Payroll Change and Late Confirmation Layout
PROJECTS-AL-CLA-CONFIRMATION CONFIRMATION hxczzhxclayt0006.ldt
Projects and Payroll Change and Late Notification Layout
PROJECTS-ALTERNATE-CLA-NOTIF NOTIFICATION hxczzhxclayt0049.ldt
Entry Level Processing Projects Pay-roll Timecard Layout
ELP-PROJECTS-PAYROLL-TIMECARD TIMECARD hxczzhxclayt0025.ldt
Entry Level Processing Projects Pay-roll Review Layout
ELP-PROJECTS-PAYROLL-REVIEW REVIEW hxczzhxclayt0032.ldt
Entry Level Processing Projects Pay-roll Confirmation Layout
ELP-PROJECTS-PAYROLL-CONF CONFIRMATION hxczzhxclayt0023.ldt
Entry Level Processing Projects Pay-roll Details Layout
ELP-PROJECTS-PAYROLL-DETAIL DETAIL hxczzhxclayt0024.ldt
Entry Level Processing Projects Pay-roll Export Layout
ELP-PROJ-PAY-EXPORT-LAYOUT EXPORT hxczzhxclayt0035.ldt
Entry Level Processing Projects Pay-roll Notification Layout
ELP-PROJECTS-PAYROLL-NOTIF NOTIFICATION hxczzhxclayt0050.ldt
1.4.4 Exception
The exception layouts delivered with the product are listed in table 4.
Layout Name Layout Code Layout Type Filename
Exception Layout Timecard Entry Page EXCEPTION-TIMECARD TIMECARD hxczzhxclayt0030.ldt
Exception Layout Timecard Review Page EXCEPTION-REVIEW REVIEW hxczzhxclayt0029.ldt Exception Layout Timecard
Confirma-tion Page
EXCEPTION-CONFIRMATION CONFIRMATION hxczzhxclayt0026.ldt
Exception Export Timecard Layout EXCEPTION-EXPORT-LAYOUT EXPORT hxczzhxclayt0027.ldt
Exception Layout Timecard Notifica-tion Page
EXCEPTION-NOTIFICATION NOTIFICATION hxczzhxclayt0046.ldt
Exception Fragmented Timecard View EXCEPTION-FRAGMENT FRAGMENT hxczzhxclayt0064.ldt
Exception OTLR Details Review Lay-out
EXCEPTION-HE-REVIEW REVIEW hxczzhxclayt0028.ldt
Exception OTLR Details Notification Layout
EXCEPTION-HE-NOTIFICATION NOTIFICATION hxczzhxclayt0045.ldt
Table 4: Exception Layouts
1.4.5 Enterprise Asset Management
The enterprise asset management layouts delivered with the product are listed in table 5.
Layout Name Layout Code Layout Type Filename
EAM Confirmation Layout EAM-CONFIRMATION CONFIRMATION eamhxclayt.ldt
EAM Review Layout EAM-REVIEW REVIEW eamhxclayre.ldt
EAM Timecard Layout EAM-TIMECARD TIMECARD eamhxclayco.ldt
Table 5: Enterprise Asset Management Layouts
1.4.6 Purchasing
The purchasing layouts delivered with the product are listed in table 6.
Layout Name Layout Code Layout Type Filename
Purchasing Timecard Layout PURCHASING-TIMECARD TIMECARD pozzhxclayt0054.ldt
Purchasing Review Timecard Layout PURCHASING-REVIEW-TIMECARD REVIEW pozzhxclayt0055.ldt
Purchasing Confirmation Timecard Layout PURCHASING-CONF-TIMECARD CONFIRMATION pozzhxclayt0056.ldt
Purchasing Notification Timecard Layout PURCHASING-NOTIF-TIMECARD NOTIFICATION pozzhxclayt0057.ldt
1.4.7 Projects-Purchasing
The projects-purchasing layouts delivered with the product are listed in table 7. Each of the layout names is prefaced with Projects-Purchasing.
Layout Name Layout Code Layout Type Filename
Timecard Layout PROJECTS-PURCHASING-TIMECARD TIMECARD pazzhxclayt0039.ldt
Review Timecard Layout PROJECTS-PURCHASING-REVIEW REVIEW pazzhxclayt0040.ldt
Confirmation Timecard Layout PROJECTS-PURCHASING-CONFIRM CONFIRMATION pazzhxclayt0041.ldt
Audit Entry Layout PA-PO-AUDIT AUDIT pazzhxclayt0042.ldt
CLA Review Layout PROJECTS-PURCHASING-CLA-REVIEW REVIEW pazzhxclayt0043.ldt
CLA Confirmation PA-PO-CLA-CONFIRM CONFIRMATION pazzhxclayt0044.ldt
Table 7: Projects-Purchasing Layouts
1.4.8 Payroll Layout delivered in Release 12.1
The payroll layout delivered for ORACLE E-BUSINESS SUITE 12.1 with the product is listed in table 8.
Layout Name Layout Code Layout Type Filename
Payroll OTLR Details Confirma-tion Layout
PAYROLL-HE-CONFIRMATION CONFIRMATION hxczzhxclayt0081.ldt
1.4.9 Project Layouts delivered in Release 12.1
The projects layouts delivered for ORACLE E-BUSINESS SUITE 12.1 with the product are listed in table 9.
Layout Name Layout Code Layout Type Filename
Projects Timecard Layout - With Project & Task details concatenated
PROJECTS-DETAILS-TIMECARD TIMECARD hxczzhxclayt0082.ldt
Projects Review Layout - With Project & Task details concatenated
PROJECTS-DETAILS-REVIEW REVIEW hxczzhxclayt0083.ldt
Projects Confirmation Layout -With Project & Task details concate-nated
PROJECTS-DET-CONFIRM CONFIRMATION hxczzhxclayt0088.ldt
Projects Details Layout - With Project & Task details concatenated
PROJECTS-DET-DETAIL DETAIL hxczzhxclayt0087.ldt
Projects Export Timecard Layout -With Project & Task details concate-nated
PROJECTS-DET-EXP-TIMECARD EXPORT hxczzhxclayt0086.ldt
Projects Notification Layout - With Project & Task details concatenated
PROJECTS-DET-NOTIF NOTIFICATION hxczzhxclayt0084.ldt
Projects Fragmented Timecard View - With Project & Task details con-catenated
PROJECTS-DET-FRAGMENT FRAGMENT hxczzhxclayt0085.ldt
Projects Change and Late Audit En-try Layout - With Project & Task details concatenated
PROJECTS-DET-AUDIT-LAYOUT AUDIT hxczzhxclayt0091.ldt
Projects Change and Late Review Layout - With Project & Task de-tails concatenated
PROJECTS-DET-AUDIT-REV REVIEW hxczzhxclayt0089.ldt
Projects Change and Late Confirma-tion Layout - With Project & Task details concatenated
PROJECTS-DET-AUDIT-CONFIRM CONFIRMATION hxczzhxclayt0092.ldt
Projects Change and Late Audit No-tification Layout - With Project & Task details concatenated
PROJECTS-DET-AUDIT-NOTIF NOTIFICATION hxczzhxclayt0090.ldt
Table 9: Projects Layouts - With Project & Task details concatenated
1.4.10 Project and Payroll Layouts delivered in Release 12.1
Layout Name Layout Code Layout Type Filename Projects and Payroll Timecard Layout - With
Project & Task details concatenated
PROJECTS-DET-ALT-TIMECARD TIMECARD hxczzhxclayt0093.ldt
Projects and Payroll Review Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-REVIEW REVIEW hxczzhxclayt0094.ldt
Projects and Payroll Confirmation Layout - With Project & Task details concatenated
PROJECTS-DET-AL-CONF CONFIRMATION hxczzhxclayt0100.ldt
Projects and Payroll Details Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-DETAIL DETAIL hxczzhxclayt0098.ldt
Projects and Payroll Export Layout - With Project & Task details concatenated
PROJPAY-DETAIL-EXPORT EXPORT hxczzhxclayt0099.ldt
Projects and Payroll Notification Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-NOTIF NOTIFICATION hxczzhxclayt0095.ldt
Projects and Payroll Fragmented Timecard View - With Project & Task details concatenated
PROJECTS-DET-ALT-FRAG FRAGMENT hxczzhxclayt0096.ldt
Projects and Payroll Change and Late Audit Entry Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-AUD-LAYOUT AUDIT hxczzhxclayt0104.ldt
Projects and Payroll Change and Late Re-view Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-CLA-REVIEW REVIEW hxczzhxclayt0101.ldt
Projects and Payroll Change and Late Con-firmation Layout - With Project & Task de-tails concatenated
PROJECTS-DET-ALT-CLA-CONF CONFIRMATION hxczzhxclayt0103.ldt
Projects and Payroll Change and Late Notifi-cation Layout - With Project & Task details concatenated
PROJECTS-DET-ALT-CLA-NOTIF NOTIFICATION hxczzhxclayt0102.ldt
Entry Level Processing Projects - Payroll Timecard Layout - With Project & Task de-tails concatenated
ELP-PROJ-DET-PAY-TIMECARD TIMECARD hxczzhxclayt0105.ldt
Entry Level Processing Projects - Payroll Re-view Layout - With Project & Task details concatenated
ELP-PROJ-DET-PAY-REVIEW REVIEW hxczzhxclayt0106.ldt
Entry Level Processing Projects - Payroll Confirmation Layout - With Project & Task details concatenated
ELP-PROJ-DET-PAY-CONF CONFIRMATION hxczzhxclayt0110.ldt
Entry Level Processing Projects - Payroll De-tails Layout - With Project & Task deDe-tails concatenated
ELP-PROJ-DET-PAY-DETAIL DETAIL hxczzhxclayt0109.ldt
Entry Level Processing Projects - Payroll Ex-port Layout - With Project & Task details concatenated
ELP-PROJ-DET-PAY-EXP-LAYOUT EXPORT hxczzhxclayt0108.ldt
Entry Level Processing Projects - Payroll No-tification Layout - With Project & Task de-tails concatenated
ELP-PROJ-DET-PAY-NOTIF NOTIFICATION hxczzhxclayt0107.ldt
1.5
Using the OAF Personalization Functionality With Timecard Configuration
In short, for any page rendered with the Oracle Time and Labor (OTL) timecard configuration utility, no UI components can be Personalized using the standard Oracle Applications Framework (OAF) functionality. All changes to the page must be made via the Oracle Time and Labor page layout definition.
The one exception to this rule are the pages rendered in the LOV pop-up windows. While the LOVs themselves are controlled by the OTL timecard configuration utility, the pages rendered in the pop-up list of values windows are not. Thus, the OAF Personalization functionality can be used to personalize those windows. For example, if the project id column in the Projects LOV pop-up should be hidden, a customer should create a personalization at the desired level and hide that column. If the columns should be renamed or reordered, again, this should be done via the personalization framework delivered with the OAF.
2
Timecard Configuration Basics
The fastest mechanism of configuring a time card is to modify the existing set of layouts that are closest to the required functionality. This white paper describes this process in detail, and illustrates with examples of common modifications. The document covers the majority of customizations, which are to the timecard header — the comments field, period list control and template control widgets — and timecard matrix — the time attributes and time entry fields. In summary, the minimal number of steps to configure a timecard layout are:
1. Use one of the seeded timecard layouts as a basis, or create a new timecard layout. 2. You must rename the timecard layout.
3. You configure the components of the timecard.
4. Upload the timecard layout to the database using FNDLOAD (see section 2.4).
NOTE: Do not use Web Application Dictionary or the OA Configuration Framework to configure the layouts. However, there are items on the OTL timecard pages such as the product branding and buttons which are outside the scope of the configurable user interface. Thus use the personalization framework to modify to those user interface components, e.g. to change the branding, or the labels on the buttons.
2.1
What can be configured on a Timecard
Figure 2: What can be Configured
PINK = Standard AOL Messages that can be modified via AOL message form
GREEN = AK prompts that can be modified in the AK region item or attribute forms
RED = Attribute components in the timecard layout that can be modified via the configuration LDTs BLACK = Information on the timecard layout that can be controlled via preferences
2.2
The Layout File
As previously mentioned, the timecard layout containing a set of user interface component, and associated qualifer descriptions, is held in a simple text file. Use FNDLOAD, the generic AOL loader utility, to upload the file data into the OTL Configurable User Interface database tables. Read the AOL documentation, within the Oracle Applications release 11i documentation, for more information on FNDLOAD. In common with all FNDLOAD compatible files, OTL delivers a configuration file, which defines the structure of the layout files. This configuration file defines the entities, and entity attributes that are present within the file, which are in the form of name value pairs unless part of the developer key for the attribute. For example, the HXC LAYOUT entity has two keys, the layout name, and the application short name that owns the layout (at the moment this is only OTL) and then a number of attributes, such as the display layout name and the layout type. In OTL, each of the entities definied in the configuration file maps to an OTL table, e.g. the HXC LAYOUTS entity maps to the HXC LAYOUTS table. Each of the entity keys, or entity attributes in the loader file maps directly or via a key to columns in those entities. E.g. DISPLAY LAYOUT NAME maps to the database column, DISPLAY LAYOUT NAME, while PARENT COMPONENT maps to the column PARENT COMPONENT ID, as the parent component specifies a key attribute of an entity. The configuration file is:
$APPL TOP/hxc/11.5/patch/115/import/hxclaytlayoutsld.lct and must be used in conjunction with FNDLOAD when uploading the layout.
2.3
Using an Existing Layout as a Basis for Customization
When creating a custom layout the easiest approach is to select one the delivered layouts, based on which is closest to your require-ments, and then use it as a starting point for your custom layout. To avoid overwriting the delivered OTL layouts you must give your new timecard layouts new names. Even if you do not plan to use the delivered layouts this change should still be made to avoid your custom layout being overwritten when OTL patches are applied to your environment. In order to rename the layout, you need to change the layout name and description in the loader file. You do this in the section at the top of the data file.
For example:
BEGIN HXC LAYOUTS "EXCEPTION-TIMECARD" "HXC" OWNER = "CUSTOM"
DISPLAY LAYOUT NAME = "Exception Layout - Timecard Entry Page" LAYOUT TYPE = "TIMECARD"
Could be changed to:
BEGIN HXC LAYOUTS "MODIFIED-EXCEPTION-TIMECARD" "HXC" OWNER = "CUSTOM"
DISPLAY LAYOUT NAME = "Modified Layout - Timecard Entry Page" LAYOUT TYPE = "TIMECARD"
These changes must be made for any layout you are modifying, and it is also a good idea to change the filename of the loader file to avoid confusion with the OTL delivered files.
2.4
Uploading Timecard Layouts
To upload the new layouts (for each of the layouts in the set you are using, or have customized) to the database execute the following command from the command line:
FNDLOAD username/password@dbname 0 Y UPLOAD $HXC TOP/patch/115/import/hxclaytlayoutsld.lct ./layout.ldt This command assumes the path environment variables are set correctly, so that the FNDLOAD executable lies on the path, and the configured layout is in the current directory and in a file called layout.ldt.
Once the modified layout is successfully uploaded, it will be available in the OTL application Preferences form and you can give it to a user, or groups of users as required.
2.5
Labels and Messages
There are two concepts used to store any text that is displayed on an OTL timecard screen - prompts and messages. In general, for small amounts of text, use a prompt, otherwise use a message, which can be considerably more descriptive. For example, the tip at the top of the timecard page is a message, while the Project label in the timecard matrix is a prompt. All component prompts and other items such as titles, button labels, etc. are defined as prompts.
2.5.1 Labels
All labels in the OTL configurable UI are translatable and customizable via the AK Developer responsibility in Oracle Applications. New labels can also be created in AK and used within the configurable UI for customized timecards. AK data for our purpose, is defined as a region containing one or more region items. For OTL, the region is just a ’container’ for all of the prompts - to see an example of this you can review the region ’HXC CUI TIMECARD’ which contains most of the prompts for the timecard entry page — see section 4. Each region item is based on an attribute, which are reusable, but for the purposes of OTL you will usually have a one-to-one mapping between region items and attributes. When creating region items there are many possible settings, but OTL will only use a subset of these fields when querying labels - the ones used, and that should be set (other than mandatory fields such as attribute name, application, length and sequence) are:
• Attribute Long Label (the text for the prompt)
• CSS Label Class Name (the CSS style name to be used for the prompt - this is optional and will be defaulted if not specified) When creating your own custom prompts you should take note of the attribute code (for the attribute referenced by your region item), along with the region code and application you have created the region items under - this information will be needed to utilize these labels within your configured timecard layout.
2.5.2 Messages
Messages in OTL use the standard Applications Object Library message functionality to provide a translatable and customizable solution for longer sections of text. When creating messages you should note the message name you have specified, along with the application name you have used.
2.6
Further Configuration Concepts
If configuring more than just the simpliest aspects of the timecard, it may be necessary to utilize the ADF. Thus, some aspects of the ADF are described in the following sections, within the context of configuring the OTL timecard interface. Specially, the business objects (BC4J or JBO) layer — these are java objects that contain or are business data — affect timecard interface configuration as the data used by the user interface components is dependent on those objects. View objects and Application Modules are two of the business objects that require configuration. An excellent discussion on these objects, and the Applications Development Framework (ADF) in general are found in the ADF Development Guidelines document available from the Oracle Technology Network.
2.6.1 View Objects
A View Object is a standard BC4J object and the primary method used to query data into OTL Self-Service applications. If you require a custom set of data to be shown on a timecard using a Choice List or LOV, then you may need to create a custom View Object to perform this query. Some customizations may be done using the Custom Choice List Components that OTL delivers. View Objects delivered by OTL should not be modified since these changes will be overwritten whenever a patch applied with changes to the View Object is applied. View Objects can be developed using the wizard supplied with JDeveloper. Once created, the BC4J objects should then be added to the classpath for the Apache/JServ server so they will be available for use within the OTL timecard screen. Note: any custom View Objects should be contained in a custom Application Module (see below for additional information).
2.6.2 Application Modules
An Application Module is a BC4J object which can be considered a ’container’ for View Objects. Note: If you create your own custom View Objects then you should also create an Application Module to contain them. In order for the timecard page to function properly with custom view objects, the OTL configurable user interface code must instantiate the custom containing application module before the custom view object from which to retrieve the appropriate business data. Thus, the configurable user interface must know the name of the custom application module. So when referencing a view object as part of the qualifiers for a user interface component, a custom application module name can be supplied using the following syntax:
QUALIFIER ATTRIBUTEx = ViewObjectName#ApplicationModuleName#ApplicationModuleClass
So for example, if you create a custom view object called ’MyViewObject’, and then created an application Module called ’MyAM’ with the full class (including package) of ’my.custom.code.MyAM’, then the qualifier would look as follows:
QUALIFIER ATTRIBUTEx = MyViewObject#MyAM#my.custom.code.MyAM
NOTE: All BC4J and Java references are case-sensitive, so it is important to ensure the reference in the layout matches that of your code.
2.6.3 Apache/JServ server
When customizations have been performed on the timecard the Apache/Jserv process may need to be ’bounced’ before the changes will take effect due to caching of data. In general the following changes will not need the middle tier to be restarted:
• Changes to the timecard layout
• Changes to prompts or messages used on the layout
The following changes require the middle tier to be restarted:
• Changes to BC4J objects (i.e. View Objects, Application Modules, etc.)
• Creation of or changes to LOV JRAD definitions (using the migration script that creates LOV definitions in JRAD from the AK data are including here also)
Any changes to OTL preference data whilst a user is logged in and impacted by those preferences will only be effective once the user has logged out and signed in again.
2.7
Delivered Configurable BC4J Objects
2.7.1 Configurable Choice List Components
To allow easy implementation of choice list components, OTL delivers a number of ’Configurable Choice Lists’. What this basically means is that we deliver a View Object based on a configurable view, so rather than a customer having to use JDeveloper to create their own BC4J view objects and application module, they can just alter the definition of the underlying configurable view and then add it onto their configured layouts.
OTL currently delivers ten of these configurable view objects: The configurable view consists of two columns:
DISPLAY VALUE VARCHAR2(30) VALUE VARCHAR2(15)
These names must be used in order that the configurable user interface can display the appopriate data in the choice list component on the timecard interface, but components will default the attributes that specify these to the same names, so they do not need to be specified in the layout. The Value column is the value that will actually be submitted with the timecard - the contents of the DisplayValue column does not need to be meaningful at all as far as the submit process is concerned (although for the benefit of anyone
View Object Name View Object Class Configurable View Name Custom1VO oracle.apps.hxc.selfservice.timecard.server.Custom1VO HXC CUI CUSTOM1 V Custom2VO oracle.apps.hxc.selfservice.timecard.server.Custom2VO HXC CUI CUSTOM2 V Custom3VO oracle.apps.hxc.selfservice.timecard.server.Custom3VO HXC CUI CUSTOM3 V Custom4VO oracle.apps.hxc.selfservice.timecard.server.Custom4VO HXC CUI CUSTOM4 V Custom5VO oracle.apps.hxc.selfservice.timecard.server.Custom5VO HXC CUI CUSTOM5 V Custom6VO oracle.apps.hxc.selfservice.timecard.server.Custom6VO HXC CUI CUSTOM6 V Custom7VO oracle.apps.hxc.selfservice.timecard.server.Custom7VO HXC CUI CUSTOM7 V Custom8VO oracle.apps.hxc.selfservice.timecard.server.Custom8VO HXC CUI CUSTOM8 V Custom9VO oracle.apps.hxc.selfservice.timecard.server.Custom9VO HXC CUI CUSTOM9 V Custom10VO oracle.apps.hxc.selfservice.timecard.server.Custom10VO HXC CUI CUSTOM10 V
Table 11: Delivered Custom Choice List View Objects
using the timecard it should obviously make some sense!). Note: For flexibility both columns are delivered as type VARCHAR2, so if you have a non-varchar2 column you will need to convert it in your view statement.
For a quick example let’s make a custom view object that does a query against PER PEOPLE F and retrieves the persons full name into DisplayValue and the period ID into Value. The SQL to perform this query would be:
SELECT full name, person id FROM per people f
So lets create a view based on this query - since the results are unsorted, lets also add an ORDER BY clause to the SQL statement so it is easier to find names in the list.
CREATE OR REPLACE FORCE VIEW HXC CUI CUSTOM1 V(display value,value) AS SELECT full name DISPLAY VALUE,to char(person id) VALUE
FROM per people f ORDER BY full name
We have used TO CHAR on the person id column to convert it to a VARCHAR2 and we have also specified the aliases for the columns so they match the expected names within the View Object. Note: Given the nature of HTML all possible selections for a choice list (both displayed text and the selection value) are part of the generated page. It is strongly advised that Choice Lists only be used when the result set shown is not excessive, otherwise the size of the page can be large, which may slow down rendering e.g. if the user is using a dial-up connection.
Information: There is an Applications Object Library profile which controls the maximum number of rows fetched for a View Object. This profile is called ’FND: View Object Max Fetch Size’ and is set to a default of 200. Without changing this profile option, this is the maximum number of choices that will available in a choice list component.
Information: OTL delivers a SQL script to create template views for all of the custom view objects - this is not run in a patch, but can be run manually to create template views for testing, or alternatively you can copy and modify the script to contain your custom view objects which can then be created by running the script. This script can be found under $HXC TOP/patch/115/sql/hxccuivw.sql. 2.7.2 Package Choice List
A package choice list is visually exactly the same as a normal choice list component on the page. The difference between the two is the data source — in the case of a normal choice list, the data is queried from a table or view via the associated View Object. For a package choice list the equivalent View Object is built from the result of a PL/SQL function call. The PL/SQL call should return the data to be shown in the choice in display value/value pairs (each separated by ’—’). The call be made with any of the supported tokens — see section 4 — for the timecard - all parameters should be of type varchar2.
Currently only one instance of a Package Choice List component can exist on a Self-Service page. A Package Choice List component is defined like any other component. It uses a context called PACKAGE CHOICE LIST of the configurable user interface component
qualifer flexfield. Attributes associated with this context, define the behaviour of this component, and tell the configurable user interface code how to call the package. In QUALIFIER ATTRIBUTE1 the package and function name to be called are specified, and QUALIFIER ATTRIBUTE2 contains the parameter list for the function. Parameters for the function call are bound by position, so it is important to make sure the order they specified in the layout matches that of the function. Literal values may also be passed in the parameter list - this could be used, for example, if you wanted to use the same function for a multiple components on the page but be able to identify each of the components and have the code behave slightly differently for each. As an example, lets create a function called ’test’ in the package ’my custom code’ that takes 3 parameters - the person id of the user, the timecard start date and a third literal value of ’TEST’:
FUNCTION test
(p resource id in varchar2
,p timecard start date in varchar2 ,p mode flag in varchar2
)
RETURN varchar2
The values for QUALIFIER ATTRIBUTE1 and QUALIFIER ATTRIBUTE2 for the component would be: QUALIFIER ATTRIBUTE1 = my custom code.test
QUALIFIER ATTRIBUTE2 = @RESOURCE IDENTIFIER ID|@TIMECARD BIND START DATE|TEST
And this is some basic function code which will convert the bind parameters into different types and return some test values to be shown in the choice list. This is the function supporting the choice list, and so this is just an example, obviously a configured function could perform any operation, as long as the return parameter meets the specification defined above.
FUNCTION test
(p resource id in varchar2
,p timecard start date in varchar2 ,p mode flag in varchar2
)
RETURN varchar2 IS
--l resource id NUMBER; l start date DATE;
l return value VARCHAR2(200);
--BEGIN
---- convert parameters
--l resource id := TO NUMBER(p resource id);
l start date := fnd date.canonical to date(p timecard start date);
---- switch base on the mode flag and set return value based on it
--IF (p mode flag = ’TEST’) THEN
l return value := ’1|Test1|2|Test2|3|Test3’; ELSE
l return value := ’10|Display1|20|Display2|30|Display3’; END IF;
--RETURN l return value;
--END test;
Note: Given the nature of HTML all possible selections for a choice list (both displayed text and the selection value) are part of the generated page. It is strongly advised that Choice Lists only be used when the result set shown is not excessive.
Info: There is an Applications Object Library profile which controls the maximum number of rows fetched for a View Object. This profile is called ’FND: View Object Max Fetch Size’ and is set to a default of 200.
2.7.3 Custom Alternate Name components
OTL Alternate Functionality is a commonly configured option on the timecard interface, because it drastically simplifies data entry for users. For example, the expenditure type seeded alias allows users to pick one value, which is converted by the system into an expenditure type, hours (element) type and a system linkage function. Thus, the user is selecting one value, rather than three. For a discussion of OTL alternate name functionality consult the OTL Application documentation.
To allow for simple configuration of alternate name components, OTL delivers five customizable alternate name objects. For the Self-Service functionality of OTL only the ’OTL Alternate Name DFF Context’ type of alternate names are supported. This type of alternate name is based on the context definition attached to the ’OTL Alternate Names’ descriptive FlexField. In the context you configure the definition of the alternate name and the value that you wish to deposit to OTL.
For example, the ELEMENTS EXPENDITURE SLF context has the following segments: • PAYROLL ELEMENTS
• EXPENDITURE TYPE
• SYSTEM LINKAGE FUNCTION • IDENTIFIER
IDENTIFIER is common to all alternate name definitions. This segment is used when you wish to define more than one alternate name with the same set of values, but with different names. In order to uniquely identify them the identifier segment should be used. For this example, when the ELEMENTS EXPENDITURE SLF alternate name type is submit, the values that are deposited are a payroll element, expenditure type and the system linkage function.
The steps for creating a custom alternate name component are
• Create context with the required segments in the OTL Alternate Names FlexField
• Create mappings for the alternate name definition. This is done using the alternate name mapping professional form. Perform a query based on the ’OTL Alternate Name DFF Context’ and your context as the type and then enter the mappings you require. For each segment of your context, you should link the correct mapping component that will be used when depositing the information into OTL.
• Once the alternate name context and mappings are complete it can be utilized by attaching the ’Self-Service timecard alternate name set defined for a user’ preference as needed.
• Next, your timecard layouts should be modified to include the custom alternate name component. These components are delivered as VO definitions that are plugged into an LOV or choicelist component with some specific qualifiers set.
Lets use an example to illustrate how an alternate name could be added onto a timecard layout with an LOV component. BEGIN HXC LAYOUT COMPONENTS
" My Timecard Layout - ExpType PriceType" OWNER = "ORACLE"
COMPONENT VALUE = "PA EXPTYPE PRICETYPE" REGION CODE = "PA CUI ALTERNATE NAME" REGION CODE APP SHORT NAME = "PA"
ATTRIBUTE CODE = "PA EXPTYPE PRICE TYPE ALIAS" ATTRIBUTE CODE APP SHORT NAME = "PA"
NAME VALUE STRING = "PA EXPTYPE PRICE TYPE ALIAS" SEQUENCE = "240"
COMPONENT DEFINITION = "LOV" RENDER TYPE = "WEB"
PARENT COMPONENT =
"My Timecard Layout - Day Scope Building blocks for worker timecard matrix" LAST UPDATE DATE = "2004/05/04"
BEGIN HXC LAYOUT COMP QUALIFIERS
"My Timecard Layout - ExpType PriceType" OWNER = "ORACLE"
QUALIFIER ATTRIBUTE CATEGORY = "LOV"
QUALIFIER ATTRIBUTE1 = "AlternateNameItem1VO" QUALIFIER ATTRIBUTE2 = "N"
QUALIFIER ATTRIBUTE3 = "HXC CUI ALIAS ITEM1 LOV" QUALIFIER ATTRIBUTE4 = "809"
QUALIFIER ATTRIBUTE5 = "5" QUALIFIER ATTRIBUTE6 =
"HxcCuiDisplayValue|ALIAS ITEM 1-DISPLAY|CRITERIA|N|HxcCuiValue|DUMMY|PASSIVE CRITERIA| N|HxcCuiValue|ALIAS ITEM 1|RESULT|N|HxcCuiDisplayValue|ALIAS ITEM 1-DISPLAY|RESULT|N" QUALIFIER ATTRIBUTE8 = "DisplayValue"
QUALIFIER ATTRIBUTE9 = "Value#NUMBER" QUALIFIER ATTRIBUTE10 =
"oracle.apps.hxc.selfservice.timecard.server.AlternateNameItem1VO" QUALIFIER ATTRIBUTE11 =
¨
EXPENDITURE TYPE PRICE TYPE|TIMECARD BIND END DATE|TIMECARD BIND START DATE" QUALIFIER ATTRIBUTE20 = "N"
QUALIFIER ATTRIBUTE21 = "Y" QUALIFIER ATTRIBUTE22 = "L"
QUALIFIER ATTRIBUTE24 = "EXPENDITURE TYPE PRICE TYPE" QUALIFIER ATTRIBUTE25 = "FLEX"
QUALIFIER ATTRIBUTE26 = "OTL ALIAS ITEM 1" QUALIFIER ATTRIBUTE27 = "Attribute1" QUALIFIER ATTRIBUTE28 = "ALIAS ITEM 1" LAST UPDATE DATE = "2004/05/04"
END HXC LAYOUT COMP QUALIFIERS END HXC LAYOUT COMPONENTS
Let’s go over the relevant qualifier settings to explain how it works.
QUALIFIER ATTRIBUTE1: This specifies the custom alternate name view object to use for this component. OTL supports 5 of these custom definitions and the VO names for each of these are:
AlternateNameItem1VO AlternateNameItem2VO AlternateNameItem3VO AlternateNameItem4VO AlternateNameItem5VO
QUALIFIER ATTRIBUTE3: For each of the custom alternate name view objects there is an LOV region delivered which references them - these regions are named:
HXC CUI ALIAS ITEM1 LOV (for use with AlternateNameItem1VO) HXC CUI ALIAS ITEM2 LOV (for use with AlternateNameItem2VO) HXC CUI ALIAS ITEM3 LOV (for use with AlternateNameItem3VO) HXC CUI ALIAS ITEM4 LOV (for use with AlternateNameItem4VO) HXC CUI ALIAS ITEM5 LOV (for use with AlternateNameItem5VO)
QUALIFIER ATTRIBUTE11: This qualifier contains the bind variables used for the alternate name definition - the first parameter should always be the type of alternate name, with the second being the timecard bind end date and the last the timecard bind start date.
QUALIFIER ATTRIBUTE26, 27 and 28: These qualifiers contain values that tell the OTL deposit process how to handle these alternate name objects. In qualifier attribute26 the OTL ALIAS ITEM1 context is specified which is used to identify the alternate name in the attribute structure - the actual context does not exist.
2.8
LOVs and JRAD/MDS
The Oracle Applications Self-Service framework now uses the MDS dictionary (aka JRAD) to store all definitions for Self Service pages including LOVs. OTL supports custom LOVs, but at the current time there is no applications interface to create LOV objects in the MDS data dictionary (other than using a tool such as JDeveloper to create the regions by hand). Consult the ADF documentation for a full description of the UI dictoinaries used in the development framework.
In order to allow continue configuration of LOVs using the AK professional forms OTL has provided a migration utility which will allow you to migrate definitions from AK to MDS.
This utility is available as a procedure in the package HXC LOV MIGRATION. The definition is: PROCEDURE migrate lov region
(p region code IN AK REGIONS VL.REGION CODE%TYPE DEFAULT NULL
,p region app short name IN FND APPLICATION.APPLICATION SHORT NAME%TYPE DEFAULT NULL ,p force IN VARCHAR2 DEFAULT NULL
);
As you can see, this procedure takes 3 optional parameters. If no parameters are specified then the procedure will attempt to migrate any LOV definitions created under application code 809 (HXC) that have no previously been migrated (there is also a script available to perform this initial migration that is run during an upgrade - this can be found at:
$APPL TOP/hxc/11.5/patch/115/sql/hxclovmig.sql).
If you are changing the definition of an LOV and need to migrate it again then you need to call the procedure with the force parameter set to ’Y’ so that the previous definition will be overwritten. For example, to migrate the LOV with the region code MY CUSTOM LOV which was created under the Oracle Time and Labor application (HXC/809), and overwriting any definition that was previously migrated you would issue the follow call to the procedure.
exec hxc lov migration.migrate lov region (p region code => ’MY CUSTOM LOV’
,p region app short name => ’HXC’ ,p force => ’Y’
);
2.8.1 LOV Custom Objects
Beginning with HXT.J Cumulative backports 1, patch 4634379, customizable list of values objects were introduced, facilitating easy addition or replacement of list of values on the timecard. The BC4J object is called CustomLov1VO, and the custom MDS region is called CuiCustomLov1RN. The BC4J object references the HXC CUI CUSTOM LOV1 V view, and this view must be present on the database before the list of values will work.
3
Examples of Common Customizations
3.1
Adding a Comment Field to the Timecard Line
The delivered timecard layouts include a details page that has a comment text area field in which the users can enter up to 2000 characters, or 240 characters if using Project Accounting as a recipient application, for commentary on the time entry.
Often people don’t want to take the functional performance hit of navigating off to the detail page, waiting for the page to render, click the Apply button on that subsequent page, and then waiting for the timecard page to render again. If the users don’t need to enter Project Accounting additional information, or if those Project Accounting additional information segments have been moved to the timecard matrix: see 3.13, then it can be very useful to move the comment text field onto the timecard matrix.
With release 11i HXT.J Cumulative Backports 1 (4634379) or later, this is now very easy, and simply a matter of adding a TimecardLineComment attribute to the layout, for example, the following component definition in the layout will add a comment text area on the right hand side of the timecard matrix - i.e. after the Day columns:
############################################################################ # Comment Field
############################################################################
BEGIN HXC LAYOUT COMPONENTS "ELP ChoiceListDff Proj-Pay Timecard Layout - Comment Text Field" OWNER = "ORACLE"
SEQUENCE = "250"
COMPONENT DEFINITION = "TEXT FIELD" RENDER TYPE = "WEB"
PARENT COMPONENT = "ELP ChoiceListDff Proj-Pay Timecard Layout - Day Scope Building blocks for worker timecard matrix"
REGION CODE = "HXC CUI TIMECARD" REGION CODE APP SHORT NAME = "HXC"
ATTRIBUTE CODE = "HXC CUI TIMECARD COMMENTS" ATTRIBUTE CODE APP SHORT NAME = "HXC"
BEGIN HXC LAYOUT COMP QUALIFIERS "ELP ChoiceListDff Proj-Pay Timecard Layout - Comment Text Field" OWNER = "ORACLE"
QUALIFIER ATTRIBUTE CATEGORY = "TEXT FIELD" QUALIFIER ATTRIBUTE1 = "N"
QUALIFIER ATTRIBUTE2 = "Y" QUALIFIER ATTRIBUTE3 = "50" QUALIFIER ATTRIBUTE4 = "3" QUALIFIER ATTRIBUTE5 = "4500" QUALIFIER ATTRIBUTE18 = "EXCLUDE" QUALIFIER ATTRIBUTE19 = "|CSV|" QUALIFIER ATTRIBUTE20 = "N" QUALIFIER ATTRIBUTE21 = "Y" QUALIFIER ATTRIBUTE22 = "R" QUALIFIER ATTRIBUTE25 = "FLEX"
QUALIFIER ATTRIBUTE26 = "TimecardLineComments" QUALIFIER ATTRIBUTE27 = "Attribute1"
END HXC LAYOUT COMP QUALIFIERS END HXC LAYOUT COMPONENTS
Clearly this is a standard text field attribute, with width 50 characters and height 3 lines. Thus, the users can clearly see 150 characters in the text area when the timecard page is rendered, and can enter up to 4500 characters. This is because while this is only one component the product distributes a TimecardLineComments attribute across all 30 segments of the timecard attribute row. Thus, rather than having just the 150 characters available in attribute1 there are 30 times 150 characters available. This also implies that only one TimecardLineComments component per timecard matrix should be configured, as the code will overwrite any values
entered into a separate TimecardLineComments component which is associated e.g. with Attribute2 of this timecard attribute. With this component in place, the timecard matrix lines appear, as per figure 3.
Figure 3: Timecard Matrix Line Comment Field
Note: None of the recipient application retrieval processes are configured to receive this data, i.e. comments entered into this field are only associated with the timecard, and while stored in the time store, they are not sent to Project Accounting, Payroll, Purchasing, Enterprise Assest Management or Human Resources.
3.2
Adding a Custom Choice List to the Timecard
Using the Configurable timecard, you can add your own custom choice lists-where the list of values is defined outside Oracle Time and Labor. We support up to ten custom lists. We access these values using a set of named views, which must have two columns present, and a choice list component attached to the layout on which the custom choice list is required. The choice list com-ponent can also be used to show custom display-only fields that are populated by a query. This can be done by making the component read-only (ie. QUALIFIER ATTRIBUTE30 = ’Y’) and enabling the ’Always Execute for Read-Only’ functionality (ie. QUALIFIER ATTRIBUTE3 = ’Y’) so that the query for the component wil.l always be executed, even if no value is stored. If multiple rows are returned by the query then only the first will be shown. The views are named: HXC CUI CUSTOMn V where n is a number between 1 and 10. For example, HXC CUI CUSTOM1 V. These views must have at least two columns and they must be called: ’DISPLAY VALUE’ and ’VALUE’. The column ’DISPLAY VALUE’ contains the values that are shown in the choice list for the user to select, and consequently should be user-friendly for your user population. The ’VALUE’ column contains the values that are actually written to the database, and are thus understood by custom code. Once the view is con-structed, you should include a choice list component in the layout of your choice. Set the view object name qualifier to CustomnVO, such as Custom1VO. Set the view object class qualifier to oracle.apps.hxc.selfservice.timecard.server.CustomnVO, such as oracle.apps.hxc.selfservice.timecard.server.Custom1VO. The custom view objects can only be used for situations where you do not need bind parameters to be present in the query - for other cases you will need to create your own View Object to use for the component.
As an example, let’s assume you want to record which machines a person worked with when submitting their time. The names and IDs of these machines are stored in a table called ?UR MACHINES. You could create the following OTL custom view:
Create or replace view HXC CUI CUSTOM6 V (DISPLAY VALUE
,VALUE) as
select machine name ,machine id
from our machines o
Then you add the following component definition to a layout:
############################################################################ # Machine Name choice list on the timecard matrix