You are on page 1of 42

WHITE PAPER Oracle OTL Time Card Configuration

Control Number: Version:

TCConfig 4.0 4.0

Oracle OTL Time Card Configuration, Release 11i Copyright 2000, 2001 Oracle Corporation All rights reserved. Primary Authors: Mark Stewart, Andrew Rundell Contributor: John Finnegan This software was not developed for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It is the customer's responsibility to take all appropriate measures to ensure the safe use of such applications if the programs are used for such purposes. This software/documentation contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. If this software/documentation is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable: Restricted Rights Legend Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in Technical Data and Computer Software (October 1988). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. If this software/documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it is delivered with Restricted Rights", as defined in FAR 52.227-14, Rights in Data - General, including Alternate III (June 1987). The information in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free. No part of this document may be reproduced or transmitted in any form or by any means electronic or mechanical, for any purpose without the express written permission of Oracle Corporation. Oracle is a registered trademark and ConText, Enabling the Information Age, Oracle7, Oracle8, Oracle8i, Oracle Access, Oracle Application Object Library, Oracle Financials, Oracle Discoverer, Oracle Web Customers, Oracle Web Employees, Oracle Workflow, Oracle Work in Process, PL/SQL, Pro*C, SmartClient, SQL*, SQL*Forms, SQL*Loader, SQL*Menu, SQL*Net, SQL*Plus, and SQL*Report are trademarks or registered trademarks of Oracle Corporation. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners.

Oracle Time & Labor Timecard Configuration


OTL Development Rev4 Summary: This document details the configuration options a timecard layout designer has when constructing a custom layout. With this release of OTL you configure AOL loader files that are then loaded into the database.

Contents
Oracle Time & Labor Timecard Configuration .............................................................................1 Contents ............................................................................................................................3 Overview ..........................................................................................................................3 Seeded Timecard Layouts .....................................................................................................4 Renaming Layouts ..............................................................................................................5 Configuring the Timecard Layout ..........................................................................................5 Time Building Blocks ......................................................................................................7 Summary of Components .................................................................................................9 Bind Variable Types ......................................................................................................12 Custom Application Modules ..........................................................................................12 Global Segments...........................................................................................................13 UI Components ............................................................................................................15 Adding Custom Choice Lists ...........................................................................................22 Adding Package Choice Lists ..........................................................................................24 Adding OTLR Detail to the Review and Confirmation Pages ................................................26 Configuring the Cost Center Component ...........................................................................27 Adding a List Of Values .................................................................................................31 Migrating LOVs from AK to the JRAD Repository .................................................................41 Uploading the New Timecard Layout ...................................................................................41

Overview
Oracle Time & Labor (OTL) gives you the ability to configure a timecard. You can choose to include or exclude a set of UI features as well as choosing the fields shown on the timecard that are used to capture information about the entered time. The timecard layouts are held in normal text files; it is possible to view the layouts delivered with OTL. An example file can found in $APPL_TOP/hxc/11.5/patch/115/import/US/hxcpaylay.ldt, where $APPL_TOP is the mount and directory where Oracle Applications was installed. The process of configuring a time card is as follows: 3

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. The timecard uses a standard Oracle FlexField, and a subsystem of OTL called the Configurable UI. The configurable UI is essentially a group of OTL database tables that hold the collection of UI features and fields that make up the timecard screen. This is a timecard layout. 4. Upload the timecard layout to the database using FNDLOAD. NOTE: Do not use Web Application Dictionary or the OA Configuration Framework to configure the layouts.

Seeded Timecard Layouts


The following table gives the file names and names of the delivered layouts. You can copy and modify these layouts. All the files are in the following directory: $HXC_TOP/patch/115/import/US/
Layout Type Timecard Layout Review Layout Confirmation Layout hxcexclyc.ldt hxcexclyc.ldt hxcprjlyc.ldt hxcpjalyc.ldt hxcelppjpylyc.ldt Details Layout Export Layout Fragmented View Layout hxcexclyf.ldt hxcpaylyf.ldt hxcprjlyf.ldt hxcpjalyf.ldt

Exception Payroll Projects Projects and Payroll ELP Projects and Payroll Exception OTLR Details Review Layout Payroll OTLR Details Review Layout Projects Change and Late Audit Entry Projects and Payroll Change and Late Audit Entry

hxcexclay.ldt hxcpaylay.ldt hxcprjlay.ldt hxcpjalay.ldt hxcelppjpylay.ldt

hxcexclyr.ldt hxcpaylyr.ldt hxcprjlyr.ldt hxcpjalyr.ldt hxcelppjpylyr.ldt hxcehelyr.ldt

N/A N/A hxcprjdet.ldt hxcpjadet.ldt hxcelppjpydet.ldt

hxcexpexception.ldt hxcexppayroll.ldt hxcprjlye.ldt hxcexpprojpay.ldt hxcelppjpylyc.ldt

hxcphelyr.ldt

hxcprjcla.ldt

hxcprjclar.ldt

hxcprjclac.ldt

hxcprjpayalt.ldt

hxcprjpayaltr.ldt

hxcprjpayaltc.ldt

The "Exception Layout" is a popular layout for customization. If you want to customize this layout to remove the cost center field, for example, you copy the exception layouts (each of the timecard, review, and confirmation pages has a different layout), and remove the section of data referring to the cost segment in each text file.

Renaming Layouts
You must give your new timecard layouts new names. 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 become:
BEGIN HXC_LAYOUTS "MODIFIED-EXCEPTION-TIMECARD" "HXC" OWNER = "CUSTOM" DISPLAY_LAYOUT_NAME = "Modified Layout - Timecard Entry Page" LAYOUT_TYPE = "TIMECARD"

You should change the names of the review and confirmation pages. You should also change the names of the ldt files.

Configuring the Timecard Layout


You can configure the majority of UI components seen on the timecard. For instance, you can change the text on the timecard that says: 'Timecard Information: Smith, Mr. John, 1'. This text is contained in a UI component (timecard page header) supported by the OTL configurable UI. Other configurable components supported by OTL include the following: the period selector box the template selector the table supporting all the time entry fields and all the fields In addition to listing configurable components, timecard designers need to add information known as layout component qualifiers. Layout component qualifiers permit fine-tuning of the user interface. OTL stores Qualifiers in the FlexField columns on the HXC_LAYOUT_COMP_QUALIFIERS table. The Flexfield is called Self Service Configurable UI FlexField . It is important to use the correct contexts with their corresponding components when configuring the timecard. The table below shows the available configurable UI component names and the component qualifier context to use when specifying the component qualifiers. Each of the 5

components is described in more detail later. Component Name Choice List Display Header Display Label Display Text Hidden Field Hourstype Table Inter Period Nav Control LOV Message Box Spacer Submit Button Table Layout Template Control Text Field Descriptive Flexfield Time Building Block Component Qualifier Context Choice List Display Header Display Label Display Text Hidden Field Hours Type Table Inter Period Navigation Control List Of Values Message Box Spacer Submit Button Table Layout [no qualifiers] Text Field Descriptive Flex Time Building Block

There is also a special context, Global Data Elements, which in the standard FlexField implementation is also applied to each context. That is, the global data elements are layout component qualifiers available in every context. There are fifteen global data elements: Display Mode Flag Display Mode List Display On New Line Show Outside Building Block Outside Direction Access Method Context View Object Attribute Component Alias Read Only Component Level (for indentation purposes on the timecard screen) ONLY TO BE USED BY ORACLE DEVELOPMENT--DO NOT USE

The effect of these qualifiers on the timecard layout is described below. But first, it is important to understand the construction of the timecard, and to consider some OTL fundamentals. 6

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 stores some 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, 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 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 can 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 also 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 to midnight on the same day). Each day may have one or more time building blocks associated with it, and these are the time entries you made when submitting the timecard. This time data model is reflected in the user interface design of the screen. 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, in the other half, we render all the child building blocks of this block. Each of these child building blocks can also be thought of 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:

Figure 1 Time Building Blocks

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 UI, and this is where the qualifiers are used to ensure that the timecard user interface makes sense. With this general strategy in mind, the component qualifiers will now be explained for each of the components. It is possible to skip this section, and simply move on to learn how to modify the seeded layout examples, but it is important to understand what effect those changes will have on the configurable UI.

Summary of Components
With all the components, and their corresponding qualifiers defined, you can customize the timecard layout without touching the delivered code. The following table indicates, for each qualifier context, the segments that are mandatory (Required = 'Y'), and the attribute numbers to use for each qualifier:
Component Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Global Data Elements Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Choice List Display Text Descriptive Flexfield Descriptive Flexfield Descriptive Flexfield Qualifier Name Component Level Style Class Display Mode Flag Display Mode List Display On New Line Show Outside Building Block Outside Direction Render Type Display Modes Access Method Context View Object Attribute Component Alias Component Identifier Read Only Viewobject Name Cache Enabled Always Execute for Read-Only Show Prompt Required Displayed Attribute Name Id Attribute Name View Object Class Bind Variable #1 Bind Variable #2 Bind Variable #3 Bind Variable #4 Bind Variable #5 Message Name Flexfield Name Flexfield App Short Name Default Context Mandatory N N N N Y N N N N N N N N N N Y N N N N N N Y N N N N N Y Y Y N Attribute Number QUALIFIER_ATTRIBUTE16 QUALIFIER_ATTRIBUTE17 QUALIFIER_ATTRIBUTE18 QUALIFIER_ATTRIBUTE19 QUALIFIER_ATTRIBUTE20 QUALIFIER_ATTRIBUTE21 QUALIFIER_ATTRIBUTE22 QUALIFIER_ATTRIBUTE23 QUALIFIER_ATTRIBUTE24 QUALIFIER_ATTRIBUTE25 QUALIFIER_ATTRIBUTE26 QUALIFIER_ATTRIBUTE27 QUALIFIER_ATTRIBUTE28 QUALIFIER_ATTRIBUTE29 QUALIFIER_ATTRIBUTE30 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE8 QUALIFIER_ATTRIBUTE9 QUALIFIER_ATTRIBUTE10 QUALIFIER_ATTRIBUTE11 QUALIFIER_ATTRIBUTE12 QUALIFIER_ATTRIBUTE13 QUALIFIER_ATTRIBUTE14 QUALIFIER_ATTRIBUTE15 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3

Descriptive Flexfield Descriptive Flexfield Descriptive Flexfield Inter-Period Navigation Control Inter-Period Navigation Control Inter-Period Navigation Control Inter-Period Navigation Control List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values List of Values Message Box Message Box Package Choice List Package Choice List Package Choice List Package Choice List Package Choice List Package Choice List Spacer Spacer Submit Button Table Layout Table Layout Table Layout Table Layout Table Layout

Show Context List Region Name Region Application ID Show Prompt Minimum Range Property Name Maximum Range Property Name Block Size Property Name

N Y Y N Y Y Y

QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE6 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3

View Object Name Cache Enabled Lov Ak Region Code Lov Ak Region Application Id Display Width Lov Criteria Result Column Mappings Displayed Attribute Name Id Attribute Name View Object Class Bind Variable #1 Bind Variable #2 Bind Variable #3 Dependant Item List Dependant Item Where Clause Type Text Message Name Function Call Cache Enabled Parameter List Show Prompt Required Always Execute for Read-Only Spacer Type Spacer Size Submit Action Number Of Columns Cell Spacing Cell Padding Cell Width Horizontal Alignment

Y Y Y Y Y Y Y N N Y N N N N N Y Y Y N N N N N Y Y Y Y N N N N

QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE6 QUALIFIER_ATTRIBUTE7 QUALIFIER_ATTRIBUTE8 QUALIFIER_ATTRIBUTE9 QUALIFIER_ATTRIBUTE10 QUALIFIER_ATTRIBUTE11 QUALIFIER_ATTRIBUTE12 QUALIFIER_ATTRIBUTE13 QUALIFIER_ATTRIBUTE14 QUALIFIER_ATTRIBUTE15 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE6 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5

10

Template Control Text Field Text Field Text Field Text Field Text Field Text Field Text Field Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block Time Building Block

Show Prompt Show Label (Component) Show Label (Parent Component) Field Width Field Height Maximum Length Css Class Read-Only Css Class Orientation Grouping Scope Building Block Number Show Horizontal Total Show Vertical Total Add Row Button Recalculate Button Delete Enabled Building Block Display Style Building Block Alignment

N Y Y N N N N N Y Y Y Y Y Y Y Y Y N N

QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE6 N QUALIFIER_ATTRIBUTE7 QUALIFIER_ATTRIBUTE1 QUALIFIER_ATTRIBUTE2 QUALIFIER_ATTRIBUTE3 QUALIFIER_ATTRIBUTE4 QUALIFIER_ATTRIBUTE5 QUALIFIER_ATTRIBUTE6 QUALIFIER_ATTRIBUTE7 QUALIFIER_ATTRIBUTE8 QUALIFIER_ATTRIBUTE9 QUALIFIER_ATTRIBUTE11 QUALIFIER_ATTRIBUTE10

11

Bind Variable Types


In order to be able to treat all components generically, the Configurable UI assumes by default that all bind variables are of type VARCHAR2. This works fine in most instances, but on some occasions it is highly desirable to bind columns with the correct type in order to maximize the performance of the query by using the correct indexes. In order to allow this, on the components that use View Objects and allow you to set the ID attribute, we have added a feature to also allow the type to be set to number if it is desired. The syntax to specify the type is to use the # as a separator after the ID attribute name, and then specify NUMBER. If no type is specified then the default type of varchar/string is used. So for example, in the LOV definition, the qualifier attribute could look like this:
QUALIFIER_ATTRIBUTE9 = "PersonId#NUMBER"

Note: when specifying the type you need to ensure that it is also set correctly in the View Object, and also the correct type is returned by the query (by casting if necessary).

Custom Application Modules


If custom View Objects are being used in a timecard, then rather than having to customize delivered OTL code, a custom Application Module should be created which contains them. Then when referring to the custom View Objects in the timecard layout, the correct Application Module should also be specified. The method for doing this, is to add the information to the View Object Name attribute using # as the separator character. The syntax of the parameters is as follows:
<View Object Name>#<Application Module Name>#<Application Module Class>

So for example, in the LOV component, a custom VO/AM could be:


QUALIFIER_ATTRIBUTE1 = "MyCustomVO#MyCustomAM#custom.MyCustomAM

The XML/Class files for the Application Module and View Object(s) should be present on the classpath of the server, otherwise a runtime error will occur.

12

Global Segments
This section describes the meaning of each of the Global segments, and any qualifiers.

Display Mode Flag and Display Mode List


These two segments indicate on which OTL screens the component should appear. OTL reuses the timecard screen throughout the self-service portion of OTL, in the templates screen, the export to CSV file and so on. Some components are not appropriate for those screens. For example, the timecard header should not be on the template screen. Use these segments to hide or show the component on the appropriate screen. The display mode flag can either be INCLUDE or EXCLUDE, and valid display modes are: VIEW-ONLY, TEMPLATE, REVIEW, CONFIRMATION, TIMECARDSAVETEMPLATE, TIMECARD-SAVEFORLATER, and TIMECARD. An example setting would be 'INCLUDE','TIMECARD' which means show this component only on the TIMECARD screen. Similarly 'EXCLUDE' 'VIEW -ONLY' means show this component everywhere except on the view only versions of the timecard.

Display On New Line


ONLY TO BE USED BY ORACLE DEVELOPMENT--DO NOT USE

Show Outside Building Block and Outside Direction


These two component qualifiers control attribution of the time building block components, and the location on the screen. In some cases, you do not want the attribution associated with a building block shown in the attribution portion of the HTML table representing the time building block. In the case of a matrix layout, all the attribution on the same row in the matrix should be the same. In this case, you set the Show Outside Building Block flag to 'Y', and the Outside Direction to 'L' to show the component to the left of the main table of text fields for time input. Setting these to 'Y' and 'R' pushes the attribution to the right of the table of time input fields. For example, on the delivered OTL exception layout, there is a table with the timecard days as columns, and attributes--in this case Hours Type--as rows of this table. Following the standard rule that attribution associated with a block is shown for each block, each column (since these are day blocks) of this table would have an Hours Type entry field. But we only want the user to enter the Hours Type information once 13

per row. Hence we use the qualifiers described above to force the Hours Type field to be rendered only once per row. These segments apply to time building block attribution, but also to controls on the row. For example, the delete icon has the Show Outside Time Building Block set to 'Y' and the Outside Direction set to 'R' in the OTL seeded timecard layout examples. Changing this 'R' to an 'L' makes the delete icon display on the left-hand-side of the table.

Access Method
For components that relate to data stored in the OTL schema, this segment indicates where the configurable UI should attempt to access the data. Possible values are: FLEX - this means that the data associated with this component comes from the time attributes table. That is, it is information stored in the OTL Information Types FlexField. TIMECARD_ATTRIBUTE - this means that the configurable UI looks for the value for this component on the timecard building block--such as the timecard comments field. TIME_BUILDING_BLOCK_ATTRIBUTE - this means that the configurable UI looks for the value of this data component within the time building blocks associated with this timecard, but not the TIMECARD building block. NOTE: This is different from the TIMECARD building block because the configurable UI has special access to the TIMECARD building block.

Context
This segment tells the configurable UI to which OTL information type the data associated with this component is attached. This is important, because OTL uses the same location in the OTL schema to store different types of information about the time. The segment might contain: "Dummy Element Context", or "Dummy Cost Center" for example. You use this context segment only if the access method is FLEX.

View Object Attribute


This segment tells the configurable UI in which column to find the data to show on the screen. For example, if the access method is FLEX, and the context is Dummy Element Context and this data component corresponds to the Hours Type information shown on the screen, the configurable UI still needs to know where in the Dummy Element Context information type the data lies. So in the case of the hours type field, this is the 'AttributeCategory' column. 14

For the FLEX style data components, the Context, and the View Object Attribute work just like OTL mappings.

Component Alias
This is another name for the component within the configurable UI. This qualifier is used by LOVs and Choice Lists to help identify components.

Read Only
For data components, setting this to 'Y' will force the configurable UI to render the data in a label field rather than a text input field. That is, the user cannot change that data.

Component Level
ONLY TO BE USED BY ORACLE DEVELOPMENT--DO NOT USE

UI Components
Components, like the time building blocks, have parent components. You refer to them by name in the layout data file. The sequence of the components is important. On the screen, children of a particular component always render immediately after the parent. Parent components and top-level components are rendered in the sequence you use in the layout data file. This section introduces each of the supported UI Components with the corresponding qualifiers only appropriate to that component.

Table Layout
This is a standard HTML table used on the timecard page to group sets of data component items. The component qualifiers associated with this component are (context TABLE_LAYOUT): Number of Columns - the number of columns in the table. NOTE: The number of rows is determined by the child components. That is, rows = ( # child components / # columns ) Cell Spacing - standard HTML cell spacing Cell Padding - standard HTML cell padding 15

Text Field
This is a data component. You use it to enter, show, and maintain timecard data. The component qualifiers associated with this component (context TEXT_FIELD) are: Show Label (Component) - This tells the configurable UI to render the component prompt with reference to the data component itself. This is typically the case for single components, or single components in table cells. Show Label (Parent Component) - This tells the configurable UI to render the component prompt with reference to the parent component, rather than the component itself. This is useful when you want sets of prompts to line up on the screen. For instance, in the case of the payroll timecard layout, the Start Time, Stop Time, and Quantity fields all lie within the same table cell. Field Width - standard HTML field width. The displayed width of the text field on the screen. Field Height - standard HTML field height. Maximum Length - standard HTML field length. The maximum amount of data (number of characters) that a user can enter into the field. CSS Class - the style sheet class to apply to the field. The CSS Class controls the fonts, colors, and text decoration styles etc., applied to the text field. NOTE: Make sure this class is available when rendering the page. Read-Only CSS Class - If the global segment Read Only is set to Y for this component, the style sheet class is taken from this segment rather than CSS Class.

Time Building Block


This is the main component of the timecard screen. These components control the overall layout of the page. You should include one TIMECARD-scope time building block in the page, and another child component that is also a time building block to contain the day and detail-scope blocks. Most other components are children of the TIMECARD-scope time building block. The component qualifiers associated with the time building block component (qualifier context TIME_BUILDING_BLOCK) are as follows: - Orientation - ONLY TO BE USED BY ORACLE DEVELOPMENT--DO NOT USE 16

Show Horizontal Total - this indicates whether the detail time building blocks total along a row, and the total shown at the end of the table. Valid values are Y and N. Show Vertical Total - the same as above, but on a column, rather than row basis. Valid values are Y and N. Add Row Button - this segment indicates whether an Add New Row button shows in the case of timecard matrix layouts. Recalculate Button - this segment indicates whether a recalculate button appears on the screen in the case of timecard matrix layouts. Day Cell Justification - Not supported at this time. This segment indicates the alignment that applies to the contents of the day cells (that is, the UI components contained within cells of the matrix layout). Valid values are L, R, and C.

Choice List
Choice lists are the UI components that provide a list of values you can choose from within a drop down list format on the timecard screen. Examples are, Hours Type or Cost Center on the seeded layouts. Choice lists must have underlying business component objects, correctly included in the application modules for timecard. NOTE: Do not change seeded components The component qualifiers appropriate to the choice list are (context CHOICE_LIST): View Object Name - The name of the corresponding view object associated with the timecard application module - for example, HoursTypeVO. View Object Class - The full class of the view object, for example oracle.apps.hxc.selfservice.timecard.server.HoursTypeVO Cache Enabled - This tells the configurable UI to re-query the values for the choice list. For the current version of the Oracle Self Service Applications Framework, this is always 'N' or left blank. Always Execute for Read Only this option determines whether or not the query should always be executed, even if no ID value for the field exists. This option is 17

used primarily when the component is being used for display fields where the result set from the query is a single value to be shown to the user. Bind Variables - these are special tokens that the configurable UI uses to execute the query associated with the VO. For example, perhaps the choice list VO requires setting the resource_id before execution. In this case, OTL provides five segments for storage. The set of available tokens are: - RESOURCE_IDENTIFIER_ID (the person ID of the person) - RESOURCE_IDENTIFIER_NAME (the full name of the person) - RESOURCE_ASSIGNMENT_NUMBER (the assignment number, as defined in Oracle HR) - HIRE_DATE (the hire date of the person in canonical format) - RESOURCE_IDENTIFIER_TYPE (for example Person) - TIMECARD_BIND_START_DATE (the start date of the timecard period) - TIMECARD_BIND_END_DATE (the end date of the timecard period) Show Prompt - this segment indicates whether a prompt shows with the choice list. If the choice list is in a matrix style layout, then it is probably not required. Displayed Attribute Name - this segment shows data to the user. It corresponds to the choice list view object attribute used as the display value. ID Attribute Name - this segment is the value that actually sits behind the choice list on the screen sent for processing.

Using the Configurable timecard, you can add your own custom choice listswhere the list of values is defined outside Oracle Time & Labor. See Adding Custom Choice Lists: page 22.

Package Choice List


Package Choice Lists are identical in appearance to the Choice List component the difference between them is that the values for a Package Choice List are obtained from a call to a function, rather than from a query. The component qualifiers associated with this component are: Function Call this is the definition of the package.function that will be called to retrieve the values for the Package Choice List component 18

Cache enabled this determines where the cache is enabled for the View Object used to store the query results. This should always be unset or set to N at the current time. Parameter List this is the list of arguments that will be passed as parameters to the function call. As with the Choice List component, the set of tokens supported by the timecard can be used here. Each parameter should be separated by |. Show Prompt this determines whether a prompt will be shown for the component. This is set to N if the component is within the timecard matrix, or the prompt is being rendered separately for formatting purposes. Required this should always be set to N at the current time. Always Execute for Read Only this option determines whether or not the query should always be executed, even if no ID value for the field exists. This option is used primarily when the component is being used for display fields where the result set from the query is a single value to be shown to the user.

Descriptive Flex
This component is used to display descriptive flexfield information on the details page. The component qualifiers associated with this component are: - Flexfield Name this is the name of the flexfield to show. - Flexfield Application Short Name this is the short name of the application that the flexfield is in. (eg. HXC, PAY, PER) - Default Context this is the default context to show when the Descriptive Flexfield is displayed. - Show Context List this determines whether a Choice List containing the list of contexts to switch between is displayed. This option should always be set to N at the moment, or not specified. - Region Name this is the region name of the page that will be used during redirects. This should always be set to HXCTIMECARDACTIVITIESPAGE. - Region Application ID this is the application ID for the region specified in the previous qualifier. This should always be set to 809.

Message Box
This is an Oracle Applications standard message box. You use this component to provide 19

information to the user. (for example, the Save for Later message box). The component qualifiers associated with the message box component (context MESSAGE_BOX) are: Type - The different types change the text decoration associated with the box. Types include Error, Warning, or confirmation. Text Message Name - The text from this message, is the text that will appear in the message box. Text message names correspond to the message name field in the FND_NEW_MESSAGES table.

Spacer
This component controls additional white space that you require on the timecard. The component qualifiers associated with the Spacer component (context: SPACER) are: Spacer Type - either horizontal or vertical. Spacer Width - the size of the spacer in pixels.

Display Text
This component displays text on the timecard screen. It has only one qualifier (component qualifier context DISPLAY_TEXT): Message Name - this corresponds to the prompt alias in the HXC_LAYOUT_COMP_PROMPTS table.

Submit Button
These are additional components on the timecard that submit the timecard data, and push that data through the processFormRequest method of the timecard (unless the button action overrides the default form submission). There is one component qualifier (context SUBMIT_BUTTON): Submit Action - Used on the timecard for various submit actions to execute when you click this button.

LOV
LOVs are UI components used when there are too many entries in the choice list of values, for the poplist UI to work well. LOV's are separate pages, and you must construct 20

them to Oracle Applications self-service framework guidelines. The component qualifiers used for the LOV (component qualifier context is LOV) are: LOV Criteria - this is a tokenized string indicating the items on the timecard page, and how they interact with the LOV page. An example of such a string is: "HxcCuiProjectNumber|PROJECT-DISPLAY|CRITERIA|N|" where HxcCuiProjectNumber is the AK region item in the LOV page, PROJECT-DISPLAY is the internal configurable UI name for the corresponding field on the timecard page CRITERIA indicates this is an LOV criteria (that is, used when building the result set for the LOV) instead of a 'RESULT' (that is, the value passed back to the timecard page) And 'N' indicates the required status (N for not required, Y for required) of the LOV criterion. AK Region Code - this is the AK region code corresponding to the LOV page. AK Region Application ID - this is the application ID of the LOV page owning application. Display Width - this is the width of the field that corresponds to the display field on the timecard that holds the return result from the LOV.

The following qualifiers are the same as for the choice list component: Bind Variables View Object Name Cache Enabled ORACLE DEVELOPMENT USE ONLY Display Attribute Name ID Attribute Name

21

Adding Custom Choice Lists


Using the Configurable timecard, you can add your own custom choice listswhere the list of values is defined outside Oracle Time & 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 component 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 will 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 constructed, 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, lets 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 OUR_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 22

Then you add the following component definition to a layout:


############################################################################ # Machine Name choice list on the timecard matrix ############################################################################ BEGIN HXC_LAYOUT_COMPONENTS "Exception Timecard Layout Machine Name" OWNER = "CUSTOM" COMPONENT_VALUE = "MACHINENAME" SEQUENCE = "110" COMPONENT_DEFINITION = "CHOICE_LIST" RENDER_TYPE = "WEB" PARENT_COMPONENT = "Exception Timecard Layout - Day Scope Building blocks for worker timecard matrix" REGION_CODE = "HXC_CUI_TIMECARD" REGION_CODE_APP_SHORT_NAME = "HXC" ATTRIBUTE_CODE = "HXC_TIMECARD_MACHINE_NAME" ATTRIBUTE_CODE_APP_SHORT_NAME = "HXC" BEGIN HXC_LAYOUT_COMP_QUALIFIERS "Exception Timecard Layout Machine Name" OWNER = "CUSTOM" QUALIFIER_ATTRIBUTE_CATEGORY = "CHOICE_LIST" QUALIFIER_ATTRIBUTE1 = "Custom6VO" QUALIFIER_ATTRIBUTE4 = "N" QUALIFIER_ATTRIBUTE10 = "oracle.apps.hxc.selfservice.timecard.server.Custom6VO" QUALIFIER_ATTRIBUTE20 = "N" QUALIFIER_ATTRIBUTE21 = "Y" QUALIFIER_ATTRIBUTE22 = "L" QUALIFIER_ATTRIBUTE25 = "FLEX" QUALIFIER_ATTRIBUTE26 = "Machine Name Info Type" QUALIFIER_ATTRIBUTE27 = "Attribute1" END HXC_LAYOUT_COMP_QUALIFIERS END HXC_LAYOUT_COMPONENTS

For a prompt to show alongside (or above) the choice list, you would need to customize the AK definition for the timecard page to add an AK region item called HXC_TIMECARD_MACHINE_NAME, and then the long label would be used as the prompt for the choice list. You can add AK region items using the AK Professional Forms. Once these two steps are done, the choice list will appear on the timecard. However, you must also create the corresponding OTL Information Types and Mapping components, and add those mapping components to your deposit process so that the information entered by the user is successfully saved to the time store. Details on creating mapping components, and adding mapping components to deposit processes can be found in the guide Implementing Oracle Time & Labor.

23

Adding Package Choice Lists


Package Choice Lists are effectively Choice List components, but based on a set of values returned from a function call rather than a direct query. They are used in places where the logic to retrieve a list of values is too complicated, or not possible to be formed by a SQL query. Currently only one instance of a Package Choice List component can exist on a Self-Service page. The function call can be defined to use any of the parameters supported on the timecard page the parameters are passed to the function by position using the order they were defined for the component. The function should return a tokenized varchar2 value containing the display value and value pairs to be used for the list. Example component definition for a Package Choice List component:
############################################################################ # Package choice list on the timecard matrix ############################################################################ BEGIN HXC_LAYOUT_COMPONENTS "My Custom Package Choice List" OWNER = "CUSTOM" COMPONENT_VALUE = "MYCUSTOM1" SEQUENCE = "200" COMPONENT_DEFINITION = "PACKAGE_CHOICE_LIST" RENDER_TYPE = "WEB" PARENT_COMPONENT = "Day Scope Building blocks for worker timecard matrix" REGION_CODE = "MY_CUSTOM_TIMECARD" REGION_CODE_APP_SHORT_NAME = "MYCUSTOMAPP" ATTRIBUTE_CODE = "MY_CUSTOM_PROMPT" ATTRIBUTE_CODE_APP_SHORT_NAME = "MYCUSTOMAPP" BEGIN HXC_LAYOUT_COMP_QUALIFIERS "My Custom Package Choice List" OWNER = "ORACLE" QUALIFIER_ATTRIBUTE_CATEGORY = "PACKAGE_CHOICE_LIST" QUALIFIER_ATTRIBUTE1 = "my_custom_package.my_custom_function" QUALIFIER_ATTRIBUTE2 = "@RESOURCE_IDENTIFIER_ID|@TIMECARD_START_DATE|@TIMECARD_END_DATE" QUALIFIER_ATTRIBUTE4 = "N" QUALIFIER_ATTRIBUTE20 = "N" QUALIFIER_ATTRIBUTE21 = "Y" QUALIFIER_ATTRIBUTE22 = "L" QUALIFIER_ATTRIBUTE25 = "FLEX" QUALIFIER_ATTRIBUTE26 = "Custom Context" QUALIFIER_ATTRIBUTE27 = "Attribute1" END HXC_LAYOUT_COMP_QUALIFIERS END HXC_LAYOUT_COMPONENTS

As can be seem, this component would call the function my_custom_function in the package my_custom_package to retrieve the list of items to show in the choice list. The function would take three parameters, passed by position, of the person id of the user, and the timecard start and end dates in canonical format. A basic template of the function called by this component is: 24

create or replace package .... my_custom_package as ...... function my_custom_function (p_resource_identifier_id in varchar2 ,p_start_date_str in varchar2 ,p_end_date_str in varchar2 ) return varchar2 -l_start_date date; l_end_date date; -is -l_start_date := FND_DATE.CANONICAL_TO_DATE(p_start_date_str); l_end_date := FND_DATE.CANONICAL_TO_DATE(p_end_date_str); ...... code to retrieve the contents of the list using the parameters passed... ...... -- example return string structure return 'display value1|id1|display value2|id2|display value3|id3'; -end my_custom_function; ...... end my_custom_package;

25

Adding OTLR Detail to the Review and Confirmation Pages


With the March 2002 release of Oracle Time and Labor, the timecard review and confirmation pages can show the user-entered timecard data as if the OTL rules and policies had been applied. When the user clicks the Review button on the timecard, the timecard calls OTLR and applies the proper rules and policies to the entered time. This OTLR API passes back a set of detail time building blocks and attributes to the timecard. The timecard will not display these blocks and attributes on the screen unless specified detail components are present in the layout. NOTE: In addition to setting up the layout correctly, you must do the following for each employee who is to review their time detail in Self-Service: Set the Evaluate OTL Rules segment of the Self Service Preference to allow Rules Evaluation to Yes. Assign the employee to OTLR structures and policies Set Autogen to Yes on the Assignment Time Information window

Creating the Detail Time Building Blocks in the Layout


Within the layout definition file, duplicate the usual TIME_BUILDING_BLOCK component that corresponds to the day matrix in the review and confirmation layout, changing the component names, component qualifiers, and sequences. Add the words Hours Explosion (exactly like that upper case for the first letter of each word, lower case for all other letters, and a space between the words) to the component name of all of the detail time components. The configurable UI will then recognize these components as requiring detail time information only, and will associate the detail time blocks and attributes with these components. Two examples are shipped with the product: Exception OTLR Details Review Layout and Payroll OTLR Details Review Layout. The filenames are hcehelyr.ldt and hcphelyr.ldt and can be found in the $APPL_TOP/hxc/11.5/import/US directory.

26

Configuring the Cost Center Component


The seeded Exception and Payroll timecard layouts include a Cost Center component. The component references a specific FND value set (US#Cost Center) and saves the cost center entries to SEGMENT1 of the Cost Allocation Key Flex Field. Within the delivered OTL timecard LDT file, the cost center is referenced in the section marked ## Cost Center ##, as follows:
############################################################################ # Cost center choice list on the timecard matrix ############################################################################ BEGIN HXC_LAYOUT_COMPONENTS "Exception Timecard Layout - Cost Center" OWNER = "CUSTOM" COMPONENT_VALUE = "COSTCENTER" SEQUENCE = "120" COMPONENT_DEFINITION = "CHOICE_LIST" RENDER_TYPE = "WEB" PARENT_COMPONENT = "Exception Timecard Layout - Day Scope Building blocks for worker timecard matrix" REGION_CODE = "HXC_CUI_TIMECARD" REGION_CODE_APP_SHORT_NAME = "HXC" ATTRIBUTE_CODE = "HXC_TIMECARD_COST_CENTER" ATTRIBUTE_CODE_APP_SHORT_NAME = "HXC" BEGIN HXC_LAYOUT_COMP_QUALIFIERS "Exception Timecard Layout - Cost Center" OWNER = "CUSTOM" QUALIFIER_ATTRIBUTE_CATEGORY = "CHOICE_LIST" QUALIFIER_ATTRIBUTE1 = "CostCenterVO" QUALIFIER_ATTRIBUTE4 = "N" QUALIFIER_ATTRIBUTE10 = "oracle.apps.hxc.selfservice.timecard.server.CostCenterVO" QUALIFIER_ATTRIBUTE20 = "N" QUALIFIER_ATTRIBUTE21 = "Y" QUALIFIER_ATTRIBUTE22 = "L" QUALIFIER_ATTRIBUTE25 = "FLEX" QUALIFIER_ATTRIBUTE26 = "Dummy Cost Context" QUALIFIER_ATTRIBUTE27 = "Attribute1" END HXC_LAYOUT_COMP_QUALIFIERS END HXC_LAYOUT_COMPONENTS

Example
Suppose you want to reference a different independent value set for the Cost Center component and save to Segment 4 of the Cost Allocation Key. Perform these steps: 1. Create the Independent Value Set, such as OTL_ACCOUNT. 2. Set up values for OTL_ACCOUNT. 3. Create a View referencing the Independent Value set, and using an OTL Custom Component. (In this example Custom Component 9.)
CREATE OR REPLACE FORCE VIEW HXC_CUI_CUSTOM9_V ( display_value ,value ) AS select flex_value display_value, flex_value_id value from fnd_flex_values_vl fv, fnd_flex_value_sets fvs where fv.flex_value_set_id = fvs.flex_value_set_id and fvs.flex_value_set_name = 'OTL_ACCOUNT'

27

(Change the name in red (OTL_ACCOUNT) to the name of the Independent Value Set you are using.) If you would like to display the Cost Segment value and the Description, use the following sql to create the view (changing the Independent Value set name and View # from 1-10)
CREATE OR REPLACE FORCE VIEW HXC_CUI_CUSTOM9_V ( display_value ,value ) AS select fv.flex_value||'-'||fv.DESCRIPTION display_value, to_char(flex_value_id) value from fnd_flex_values_vl fv, fnd_flex_value_sets fvs where fv.flex_value_set_id = fvs.flex_value_set_id and fvs.flex_value_set_name = 'OTL_ACCOUNT'

1. Modify the Cost Center section of the Layout, Review, and Confirmation Pages with the required changes (displayed below in RED).
############################################################################ # Cost center choice list on the timecard matrix ############################################################################ BEGIN HXC_LAYOUT_COMPONENTS "Exception Timecard Layout - Cost Center" OWNER = "CUSTOM" COMPONENT_VALUE = "COSTCENTER" SEQUENCE = "120" COMPONENT_DEFINITION = "CHOICE_LIST" RENDER_TYPE = "WEB" PARENT_COMPONENT = "Exception Timecard Layout - Day Scope Building blocks for worker timecard matrix" REGION_CODE = "HXC_CUI_TIMECARD" REGION_CODE_APP_SHORT_NAME = "HXC" ATTRIBUTE_CODE = "HXC_TIMECARD_COST_CENTER" ATTRIBUTE_CODE_APP_SHORT_NAME = "HXC" BEGIN HXC_LAYOUT_COMP_QUALIFIERS "Exception Timecard Layout - Cost Center" OWNER = "CUSTOM" QUALIFIER_ATTRIBUTE_CATEGORY = "CHOICE_LIST" QUALIFIER_ATTRIBUTE1 = "Custom9VO" QUALIFIER_ATTRIBUTE4 = "N" QUALIFIER_ATTRIBUTE10 = "oracle.apps.hxc.selfservice.timecard.server.Custom9VO" QUALIFIER_ATTRIBUTE20 = "N" QUALIFIER_ATTRIBUTE21 = "Y" QUALIFIER_ATTRIBUTE22 = "L" QUALIFIER_ATTRIBUTE25 = "FLEX" QUALIFIER_ATTRIBUTE26 = "Dummy Cost Context" QUALIFIER_ATTRIBUTE27 = "Attribute4" END HXC_LAYOUT_COMP_QUALIFIERS END HXC_LAYOUT_COMPONENTS

The Cost Segment Values will be deposited in Segment 4 (QUALIFIER_ATTRIBUTE27 = "Attribute4" ) The Value Set will be using the JAVA component Custom9VO, which calls the view created in step 3 (HXC_CUI_CUSTOM9_V). The view returns the independent value set. You must rename the Qualifiers and Components sections, as outlined in Renaming Layouts, page 5. 28

If you need to place additional Cost Center Segments on the Self Service Layout, you must make the following additional changes to the .LDT: 1. Show the Cost Center Choice List on Timecard matrix X times in the ldt file (where X is the number of times a cost allocation key flex segment should be shown) 2. Change the entry for SEQUENCE = 120 (above) to a value higher than 120, to show after the 1st Cost Center segment 3. Use a unique name for the new cost center segments in the lines in RED (above) 4. Ensure the BEGIN HXC_LAYOUT_COMPONENTS has a unique name for each Cost Allocation Key Flex Segment and matches the BEGIN HXC_LAYOUT_COMP_QUALIFIERS 5. Ensure the View and VO numbers select the correct Value Set items 6. Ensure QUALIFIER_ATTRIBUTE27 reflects the correct Cost Allocation Key Flexfield 7. Define AK Attributes and Regions Items for the new segments, to display a Label other than Cost Centersee AK Items for the Labels on the Timecard, below. 8. Associate the new AK Regions and Attributes to the following lines in the Cost Center section of the LDT file: REGION_CODE = "HXC_CUI_TIMECARD" REGION_CODE_APP_SHORT_NAME = "HXC" ATTRIBUTE_CODE = "HXC_TIMECARD_COST_CENTER" ATTRIBUTE_CODE_APP_SHORT_NAME = "HXC" The text in red here must use the new AK Region and Attributes for the Cost Allocation Key Flex Labels.

AK Items for the Labels on the Timecard

Define Attributes Attribute ID Attribute Name Application ApplicationData Type Label Define Region Region ID

VALUE (Used on Timecard LDT File as


ATTRIBUTE_CODE)

Meaningful Name (Used in Region ) Oracle Time and Labor (or shown as Capture) VARCHAR2 Value to Show on Timecard

VALUE (Used on Timecard LDT File as 29

REGION_CODE)

Region Name Application Object Name Region Style Number of Columns

Meaningful Name Oracle Time and Labor (or shown as Capture) ICX_PROMPTS Page Layout 1

After you have defined the Region, select <Region Items> button to add the attributes to the Region. Attribute Type Attribute Application Oracle Time and Labor Attribute Name Attribute Name (created above) Sequence # Item Style Text

30

Adding a List Of Values


Creating a list of values (LOV) involves the following steps: 1. Create the View Object for the LOV 2. Create AK attributes used for the LOV screen 3. Create an AK region for rendering the LOV screen 4. Create AK region items inside the AK region for the LOV page 5. Modify a layout to include the LOV component 6. Include the new LOV View Object into your Apache/JServ environment To further illustrate this process we will use a specific example and show the steps required to implement this example in a timecard layout. Scenario: Include a LOV on the timecard that allows the user to select from a list of people visible from their security profile. The user should be able to search on criteria such as full name, last name, date of birth, employee number, and the business group of the person. Additionally, the Business Group ID of the person must be returned to a hidden field already defined on the screen with the alias of BUSINESSGROUP. 1. Create the View Object for the LOV The query used for the view object should select all the columns that you would like to see shown in the LOV page. In addition the query should select any other columns that you wish to restrict the query by or save as an attribute on the timecard. Initial step is to define the query according to your requirements, so for our example:
select pers.person_id ,pers.full_name ,pers.last_name ,pers.date_of_birth ,pers.employee_number ,bg.business_group_id ,bg.name business_group_name from per_people_f pers ,per_business_groups bg where pers.business_group_id = bg.business_group_id

Next, you need to decide the class and view usage name for your VO. Class Name: my.custom.server.CustomPersonVO View Usage Name: CustomPersonVO 2. Create AK attributes used for the LOV screen 31

Use the Define Attributes window, which is available from the professional forms AK Developer responsibility. Define attributes for each of the items that you need to show on the LOV page. Complete the following fields: Attribute ID, Attribute Name, Application, Data Type, Value Length, Style and Label. Leave the other fields blank or at their default value. So for our example, you would need to create attributes for the following fields: person_id full_name last_name date_of_birth employee_number business_group_id business_group_name Attribute ID: CUSTOM_PERSON_ID Attribute Name: My Custom LOV - Person ID Application: Oracle Time and Labor Data type: Number Value Length: 15 Style: Text Label: Person ID Attribute ID: CUSTOM_FULL_NAME Attribute Name: My Custom LOV - Full Name Application: Oracle Time and Labor Data type: Varchar2 Value Length: 240 Style: Text Label: Full Name Attribute ID: CUSTOM_LAST_NAME Attribute Name: My Custom LOV - Last Name Application: Oracle Time and Labor Data type: Varchar2 Value Length: 40 Style: Text Label: Last Name Attribute ID: CUSTOM_DATE_OF_BIRTH Attribute Name: My Custom LOV - Date of Birth Application: Oracle Time and Labor 32

Data type: Value Length: Style: Label:

Date 1 Text Date of Birth

Attribute ID: CUSTOM_EMPLOYEE_NUMBER Attribute Name: My Custom LOV - Employee Number Application: Oracle Time and Labor Data type: Varchar2 Value Length: 30 Style: Text Label: Employee Number Attribute ID: CUSTOM_BUSINESS_GROUP_ID Attribute Name: My Custom LOV - Business Group ID Application: Oracle Time and Labor Data type: Number Value Length: 15 Style: Text Label: Business Group ID Attribute ID: CUSTOM_BUSINESS_GROUP_NAME Attribute Name: My Custom LOV - Business Group Name Application: Oracle Time and Labor Data type: Varchar2 Value Length: 60 Style: Text Label: Business Group Name 3. Create an AK region for rendering the LOV screen Region ID: MY_CUSTOM_LOV Region Name: My custom LOV Application Name: Oracle Time and Labor Object Name: ICX_PROMPTS Region Style: List of Values Application Module Definition Name: oracle.apps.hxc.selfservice.timecard.server.TimecardAM Display Rows: 10 (or however many rows you want displayed in the LOV) Controller Object Type: oracle.apps.hxc.selfservice.configui.webui.LovCO Add Indexed Children: (checked) (Leave all other fields blank or to their default value) 33

Save the record. 4. Create AK region items inside the AK region for the LOV page Next you need to create region items for each of the things you want to show on the LOV. Using the AK Regions window, query the region that you created in the previous step, and with that row selected, click on the Region Items button. Complete the following fields: Attribute Type, Application, Attribute Name, Sequence, Node Display, Queryable, View Usage Name, View Attribute Name. In addition, make a note of the value for Item Name - this will be auto-generated from the attribute code and you do not need to change it, but you need to know it for when you create the LOV component definition. So for our example, you would create the following region items inside the LOV region. Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Person ID Sequence: 10 Node Display: Checked Queryable: Checked Item Name: CustomPersonId View Usage Name: CustomPersonVO View Attribute Name: PersonId Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Full Name Sequence: 20 Node Display: Checked Queryable: Checked Item Name: CustomFullName View Usage Name: CustomPersonVO View Attribute Name: FullName Attribute Type: Application: Attribute Name: Sequence: Node Display: Attribute Oracle Time and Labor My Custom LOV - Last Name 30 Checked 34

Queryable: Checked Item Name: CustomLastName View Usage Name: CustomPersonVO View Attribute Name: LastName Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Date of Birth Sequence: 40 Node Display: Checked Queryable: Checked Item Name: CustomDateOfBirth View Usage Name: CustomPersonVO View Attribute Name: DateOfBirth Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Employee Number Sequence: 50 Node Display: Checked Queryable: Checked Item Name: CustomEmployeeNumber View Usage Name: CustomPersonVO View Attribute Name: EmployeeNumber Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Business Group ID Sequence: 60 Node Display: Checked Queryable: Checked Item Name: CustomBusinessGroupId View Usage Name: CustomPersonVO View Attribute Name: BusinessGroupId Attribute Type: Attribute Application: Oracle Time and Labor Attribute Name: My Custom LOV - Business Group Name Sequence: 70 Node Display: Checked Queryable: Checked Item Name: CustomBusinessGroupName View Usage Name: CustomPersonVO View Attribute Name: BusinessGroupName 35

5. Modify a layout to include the LOV component Qualifiers for the LOV component QUALIFIER_ATTRIBUTE1 - View Object Name This is the View Usage name of the View Object to be used for rendering the LOV. The View Usage name is simply the name given to the instance of the view object in the application module. QUALIFIER_ATTRIBUTE3 - LOV AK Region Code This is the AK Region Code of the LOV region that has been defined for the component. If you are customizing a LOV then you will almost certainly need to create a new AK region for it. QUALIFIER_ATTRIBUTE4 - LOV AK Region Application ID This is just the Application ID that the AK Region specified above was created in. QUALIFIER_ATTRIBUTE5 - Display Width This is the character width of the LOV text field on the page. Note: due to the way that HTML form components are interpreted by browsers--due mainly to the use of proportional fonts--the width of the field may not be the 'expected' width. QUALIFIER_ATTRIBUTE6 - LOV Criteria This qualifier is used to set up the criteria used for the LOV. It is a tokenized string consisting of 4 items per criteria, each separated by a pipe symbol '|'. Note: when a LOV component is rendered by the configurable UI it will actually render two components. One contains the actual ID that is submitted and saved with the timecard (this component can be referred to by the alias given to the LOV component in the layout definition). This ID component is rendered on the page as a hidden field and the ID value in the LOV should be returned to it. The other field that is rendered is the actual text field that can be seen on the page. This field contains the 'display' value for the LOV. This field has an implicit alias given to it of the base alias name followed by '-DISPLAY'. This alias should also be populated as a result of the LOV. Bear in mind that if you create other fields on the screen that are dependant on the ID of a field, then you should also take into account the 'display' value to cover the scenario where a user is manually entering values into the LOV text fields (in this scenario the ID fields will not be populated). QUALIFIER_ATTRIBUTE7 - Result Column Mappings 36

If there are other fields on the screen that you want to be populated as a result of the selection in the LOV then you should specify them here. For example, the System Linkage Function comes back with the Expenditure Type. Note that the in page population of result fields is handled in qualifier_attribute6 as stated above - this qualifier is used for the case when the LOV functionality is not used on the screen and a value is entered manually. In this scenario, when the page is submitted, the query for the LOV will be executed with the manually entered value and if a unique result is found the 'result' columns will be populated using the attribute in the VO specified by this qualifier. To allow multiple result columns to be specified, this qualifier is a token separated string consisting of 'ALIAS|View Object Attribute Name' pairs. So for example, if you have a query and wish the component aliased as 'PROJECT' to contain the value from the 'ProjectId' column in the VO, and the component aliased as 'PROJECTCODE' to contain the value from the 'ProjectCode' column in the VO, the qualifier would be: QUALIFIER_ATTRIBUTE7 = "PROJECT|ProjectId|PROJECTCODE|ProjectCode" QUALIFIER_ATTRIBUTE8 - Displayed Attribute Name This is the name of the VO Attribute that will be used for the value displayed in the LOV field on the screen. QUALIFIER_ATTRIBUTE9 - ID Attribute Name This is the name of the VO Attribute that will be used for the value actually stored for the LOV component (usually a unique ID for the displayed value). QUALIFIER_ATTRIBUTE10 - View Object Class This is the VO class (including full package specification). QUALIFIER_ATTRIBUTE11 - Bind Variable #1 This is the value or alias used for the first bind parameter in the VO (not used usually). QUALIFIER_ATTRIBUTE12 - Bind Variable #2 This is the value or alias used for the second bind parameter in the VO (not used usually). QUALIFIER_ATTRIBUTE13 - Bind Variable #3 This is the value or alias used for the third bind parameter in the VO (not used usually). QUALIFIER_ATTRIBUTE14 - Dependent Item List This qualifier contains the mappings between items in the LOV and aliases in the 37

timecard for the purposes of building the query clause at runtime. There is a third value which is used to specify if this mapping is also to be used when the LOV is built - in most cases this will be set to Y, but may be set to N in cases where the appropriate values are being passed into the LOV code using the criteria. The value for this qualifier is a double token separated list - for each dependent item there is a tokenized string in the form 'Lov Item Name|Alias|Use in LOV'. If there is more than one dependent item more can be added, separating each one with a hash '#' i.e. 'Item1|ALIAS1|Y#Item2|ALIAS2|Y' QUALIFIER_ATTRIBUTE15 - Dependent Item Where Clause This qualifier is linked to the dependent item list qualifier outlined above. The value for this qualifier is also a token separated string and contains the fragments of SQL to be added to the where clause if a value for the dependent item exists. There should be one entry on this list for each of the dependent items specified in qualifier 14 - each of the entries is separated by a hash sign '#'. In order to reference the value of the dependent item, you can prefix the LOV item name with two colons. For example 'my_column = ::Item1'. Note that for LOVs the displayed value is implicitly added to the where clause using UPPER to make it case-insensitive. So for our example, the component definition is:######################################################################## # My Custom Person LOV # ####################################################################### BEGIN HXC_LAYOUT_COMPONENTS "My Custom Layout - Custom Person LOV" OWNER = "CUSTOM" COMPONENT_VALUE = "CUSTOMPERSON" SEQUENCE = "140" COMPONENT_DEFINITION = "LOV" RENDER_TYPE = "WEB" PARENT_COMPONENT = "My Custom Layout - Day Scope Building blocks for worker timecard matrix" REGION_CODE = "MY_CUSTOM_AK_PROMPT_REGION" REGION_CODE_APP_SHORT_NAME = "HXC" ATTRIBUTE_CODE = "MY_CUSTOM_PERSON_PROMPT" ATTRIBUTE_CODE_APP_SHORT_NAME = "HXC" BEGIN HXC_LAYOUT_COMP_QUALIFIERS "My Custom Layout - Custom Person LOV" OWNER = "CUSTOM" QUALIFIER_ATTRIBUTE_CATEGORY = "LOV" QUALIFIER_ATTRIBUTE1 = "CustomPersonVO" QUALIFIER_ATTRIBUTE2 = "N" QUALIFIER_ATTRIBUTE3 = "MY_CUSTOM_LOV" QUALIFIER_ATTRIBUTE4 = "809" QUALIFIER_ATTRIBUTE5 = "12" # display width QUALIFIER_ATTRIBUTE6 = "CustomFullName|CUSTOMPERSONDISPLAY|CRITERIA|N|CustomPersonId|CUSTOMPERSON|RESULT|N|CustomFullName|CUSTOMPERSONDISPLAY|RESULT|N|CustomBusinessGroupId|BUSINESSGROUP|RESULT|N" QUALIFIER_ATTRIBUTE7 = "BUSINESSGROUP|CustomBusinessGroupId" QUALIFIER_ATTRIBUTE8 = "CustomFullName" QUALIFIER_ATTRIBUTE9 = "CustomPersonId"

38

QUALIFIER_ATTRIBUTE10 = "my.custom.server.CustomPersonVO" QUALIFIER_ATTRIBUTE20 = "N" QUALIFIER_ATTRIBUTE21 = "Y" QUALIFIER_ATTRIBUTE22 = "L" QUALIFIER_ATTRIBUTE25 = "FLEX" QUALIFIER_ATTRIBUTE26 = "MYFLEX" QUALIFIER_ATTRIBUTE27 = "Attribute1" QUALIFIER_ATTRIBUTE28 = "CUSTOMPERSON" END HXC_LAYOUT_COMP_QUALIFIERS END HXC_LAYOUT_COMPONENTS

Note: If you wish to also show the new LOV field on the review and confirmation layouts you will need to modify them to include the component as well. The easiest way to accomplish this is to copy the component definition over from the timecard layout, changing the component name, parent component name and qualifier name. Then you just need to modify the copied definition to make it render as a read only text field--this is done by adding a value of Y for qualifier_attribute30:
QUALIFIER_ATTRIBUTE30 = Y

6. Include the new LOV View Object into your Apache/Jserv environment First of all you need to compile any Java code that was generated when you created your View Objects. Typically you will have a VOImpl.java file, but there are others you can choose to create when you generate your VO. Once you have the class files you will need to get these and the xml file to your apache/JServ environment. The easiest way to do this is to create a directory and then prefix this to your JServ classpath. Note: In the directory you will need to maintain the full structure of the package you used to create your VO. For our example, the files are in the package 'my.custom.server'. So in the directory you add to your classpath you should have the following structure/files (assuming 'custom' is the name of your directory): custom/my <directory> custom/my/custom/ <directory> custom/my/custom/server/ <directory> custom/my/custom/server/CustomPersonVO.xml custom/my/custom/server/CustomPersonVOImpl.class After altering the JServ classpath to include your directory you should bounce Apache/JServ for the changes to take effect. The final task needed to implement your new LOV is to compile your modified layout against the database, and if necessary assign it to the relevant users via the preference screen. 39

40

Migrating LOVs from AK to the JRAD Repository


From HXT mini-pack E onwards, Oracle Time and Labor is based on the latest Oracle Applications Framework that now uses the MDS repository as the source for Self-Service pages. If you have created custom LOV regions in AK to use with the OTL configurable timecard then these have to be migrated to the MDS repository so that the timecard page will continue to function. If you are at the HXT E or newer patch level then any custom LOVs that existed under The Oracle Time and Labor should have been automatically migrated to the MDS repository. If you have created any LOV under different applications then these will need to be migrated separately. In order to allow for LOV regions created in AK subsequent to the migration, or under different applications a function is also available that will perform this migration. To manually migrate an LOV from AK to the MDS repository the function call is:
hxc_lov_migration.migrate_lov_region

The function call takes 3 parameters: LOV Region Code - the region code for the custom LOV Application Short Name - the short name for the application the LOV was created under (eg. HXC) Force Mode (Y/N) - if set to 'Y' then the LOV will be re-migrated even if it already exists in the MDS repository (eg. if you are testing a new LOV and make a change in AK and wish to migrate the LOV again) To run the package in SQLPLUS the following command could be used:
sqlplus> execute hxc_lov_migration.migrate_lov_region ('<lov_region_code>', '<app_short_name'>, '<force_mode>');

Note: After migration LOVs the Apache/Jserv server must be restarted before the LOVs can be used.

Uploading the New Timecard Layout


To upload the new layouts (for the timecard layout, review layout and confirmation layout) to the database execute the following command: 41

% FNDLOAD username/password@dbname 0 Y UPLOAD $HXC_TOP/patch/115/import/hcsscui.lct ./timecardlayout.ldt

The modified layouts will be available in the Preferences window and you can give them to a user, or groups of users as required.

42

You might also like